Evaluations

Evaluations in Semantikmatch are automated processes used to assess candidate applications against predefined criteria. These evaluations are represented as scorecard results that show the total score and detail items for each assessment. On this page, we'll explore the different evaluation endpoints you can use to retrieve and delete evaluations programmatically.

The evaluation model

The evaluation model contains information about the results of an automated evaluation process, including the details of all scorecard items that were applied to the application.

Properties

Name
id
Type
string
Description
Unique identifier for the evaluation (scorecard result).
Name
application_id
Type
string
Description
Identifier for the associated application.
Name
job_id
Type
string
Description
Identifier for the associated job.
Name
status
Type
string
Description
Status of the evaluation (e.g., "finished", "pending", "processing").
Name
total_score
Type
number
Description
Total score across all scorecard items.
Name
created_at
Type
string
Description
ISO timestamp of when the evaluation was created.
Name
updated_at
Type
string
Description
ISO timestamp of when the evaluation was last updated.
Name
scorecard_details
Type
array
Description
Array of scorecard item details showing individual assessments.
Name
candidate
Type
object
Description
Information about the candidate being evaluated (id, firstname, lastname, email).
Name
job_name
Type
string
Description
Name of the job associated with this evaluation.

Scorecard Detail Item

Name
status
Type
string
Description
Status of the scorecard item evaluation (e.g., "success", "not_met").
Name
condition
Type
string
Description
The condition used for evaluation (e.g., "EQ", "HigherThan").
Name
criteria_id
Type
string
Description
ID of the associated criteria.
Name
description
Type
string
Description
Description of the scoring rule.
Name
processed_at
Type
string
Description
Timestamp of when the item was processed.
Name
scorecard_id
Type
string
Description
ID of the associated scorecard.
Name
score_applied
Type
number
Description
Points applied based on the assessment.
Name
value_compared
Type
string
Description
The value being compared against.
Name
value_evaluated
Type
string
Description
The actual value that was evaluated.
Name
criteria_result_id
Type
string
Description
ID of the related criteria result.
Name
reason
Type
string
Description
Reason for not meeting the condition (only present when status is "not_met").

GET/api/evaluations

Fetch all evaluations

This endpoint allows you to retrieve all evaluations. You can filter the results using query parameters such as status, job_id, application_id, start_date, end_date, or fetch specific evaluations using comma-separated ids.

Query Parameters

Name
status
Type
string
Description
Filter by evaluation status (e.g., "finished", "pending").
Name
job_id
Type
string
Description
Filter by job ID.
Name
application_id
Type
string
Description
Filter by application ID.
Name
start_date
Type
string
Description
Filter for evaluations created on or after this date (ISO format).
Name
end_date
Type
string
Description
Filter for evaluations created on or before this date (ISO format).
Name
ids
Type
string
Description
Comma-separated list of specific evaluation IDs to retrieve.

Get Evaluations

curl https://gateway.semantikmatch.com/api/evaluations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G --data-urlencode "application_id=3ca8e587-d6fd-41d4-9074-ac377f5dee29"

Response

[
  {
    "id": "56917",
    "application_id": "c4501559-a55d-4457-99ac-64030879cf0c",
    "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
    "status": "finished",
    "total_score": 6,
    "created_at": "2025-05-05T08:12:47.505Z",
    "updated_at": "2025-05-05T08:14:01.070Z",
    "candidate": {
      "id": "9a27d6b5-e6c1-4af2-9d76-1ab85cb82f22",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john.d@example.com"
    },
    "job_name": "Admissions Evaluation",
    "scorecard_details": [
      {
        "status": "success",
        "condition": "EQ",
        "criteria_id": "74",
        "description": "Value equals 100 (-2 points)",
        "processed_at": "2025-05-05T08:13:20.658Z",
        "scorecard_id": "12",
        "score_applied": -2,
        "value_compared": "100",
        "value_evaluated": "Des résultats en baisse, un devoir maison non rendu malgré un délai conséquent, aucun investissement dans la matière.",
        "criteria_result_id": "584"
      },
      {
        "status": "success",
        "condition": "HigherThan",
        "criteria_id": "71",
        "description": "Value > 0 (+2 points)",
        "processed_at": "2025-05-05T08:13:34.003Z",
        "scorecard_id": "14",
        "score_applied": 2,
        "value_compared": "0",
        "value_evaluated": "3",
        "criteria_result_id": "585"
      }
    ]
  }
]

GET/api/evaluations/:id

Fetch a specific evaluation by ID

This endpoint allows you to retrieve a specific evaluation by providing its ID. The response includes the scorecard result, detailed scorecard items, and information about the candidate and job.

Get Evaluation by ID

curl https://gateway.semantikmatch.com/api/evaluations/56917 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "56917",
  "application_id": "c4501559-a55d-4457-99ac-64030879cf0c",
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "status": "finished",
  "total_score": 6,
  "created_at": "2025-05-05T08:12:47.505Z",
  "updated_at": "2025-05-05T08:14:01.070Z",
  "candidate": {
    "id": "9a27d6b5-e6c1-4af2-9d76-1ab85cb82f22",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john.d@example.com"
  },
  "job_name": "Admissions Evaluation",
  "scorecard_details": [
    {
      "status": "success",
      "condition": "EQ",
      "criteria_id": "74",
      "description": "Value equals 100 (-2 points)",
      "processed_at": "2025-05-05T08:13:20.658Z",
      "scorecard_id": "12",
      "score_applied": -2,
      "value_compared": "100",
      "value_evaluated": "Des résultats en baisse, un devoir maison non rendu malgré un délai conséquent, aucun investissement dans la matière.",
      "criteria_result_id": "584"
    },
    {
      "status": "success",
      "condition": "HigherThan",
      "criteria_id": "71",
      "description": "Value > 0 (+2 points)",
      "processed_at": "2025-05-05T08:13:34.003Z",
      "scorecard_id": "14",
      "score_applied": 2,
      "value_compared": "0",
      "value_evaluated": "3",
      "criteria_result_id": "585"
    },
    {
      "reason": "Condition not met",
      "status": "not_met",
      "condition": "HigherThan",
      "criteria_id": "72",
      "description": "Value > 0 (+2 points)",
      "processed_at": "2025-05-05T08:13:47.505Z",
      "scorecard_id": "11",
      "score_applied": 0,
      "value_compared": "0",
      "value_evaluated": "0",
      "criteria_result_id": "587"
    }
  ]
}

DELETE/api/evaluations/:id

Delete a specific evaluation by ID

This endpoint allows you to delete a specific evaluation by its ID. The response includes details about the deleted evaluation.

Delete Evaluation

curl -X DELETE https://gateway.semantikmatch.com/api/evaluations/56917 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "message": "Evaluation deleted successfully",
  "evaluation": {
    "id": "56917",
    "application_id": "c4501559-a55d-4457-99ac-64030879cf0c",
    "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
    "status": "finished",
    "total_score": 6,
    "created_at": "2025-05-05T08:12:47.505Z",
    "updated_at": "2025-05-05T08:14:01.070Z",
    "candidate": {
      "id": "9a27d6b5-e6c1-4af2-9d76-1ab85cb82f22",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john.d@example.com"
    },
    "job_name": "Admissions Evaluation",
    "scorecard_details": [
      {
        "status": "success",
        "condition": "EQ",
        "criteria_id": "74",
        "description": "Value equals 100 (-2 points)",
        "scorecard_id": "12",
        "score_applied": -2,
        "value_compared": "100",
        "value_evaluated": "Des résultats en baisse...",
        "criteria_result_id": "584"
      }
    ]
  }
}

Evaluation Re-run Behavior

When an evaluation is deleted, the Semantikmatch system automatically re-runs the evaluation for the associated application. This process is useful for cases where the criteria or the candidate’s data have changed, and a fresh evaluation is required.