Evaluations

Evaluations in Semantikmatch are automated processes used to assess candidate applications against predefined criteria. Once an application is submitted, the evaluation process generates results based on the associated criteria. On this page, we'll explore the different evaluation endpoints you can use to retrieve and delete evaluations programmatically. Deleting an evaluation automatically triggers a re-evaluation of the associated application.

The evaluation model

The evaluation model contains information about the results of an automated evaluation process, including the results of each criterion that was applied to the application.

Properties

Name
id
Type
number
Description
Unique identifier for the criteria result.
Name
criteria_id
Type
number
Description
Identifier for the associated evaluation criteria.
Name
result
Type
boolean
Description
Indicates whether the criteria was met.
Name
evaluated_at
Type
timestamp
Description
Timestamp of when the criteria was evaluated.
Name
score
Type
number
Description
Score assigned to the criteria result.
Name
score_justification
Type
string
Description
Explanation of the score assigned.
Name
citations
Type
array
Description
List of citations supporting the criteria result.
Name
status
Type
string
Description
Status of the criteria evaluation (e.g., "finished").
Name
application_id
Type
string
Description
Identifier for the associated application.
Name
job_id
Type
string
Description
Identifier for the associated job.
Name
section
Type
number
Description
Section identifier for the criteria result.
Name
confidence
Type
number
Description
Confidence level of the criteria result.
Name
confidence_justification
Type
string
Description
Explanation of the confidence level.

GET/v1/evaluations

Fetch all evaluations

This endpoint allows you to retrieve all evaluations. You can filter the results using query parameters such as criteria_type, status, job_id, and application_id.

Request

GET

/v1/evaluations

curl https://api.semantikmatch.com/v1/evaluations \
  -H "Authorization: Bearer {token}" \
  -G --data-urlencode "criteria_type={criteria_type}" \
  --data-urlencode "status={status}" \
  --data-urlencode "job_id={job_id}" \
  --data-urlencode "application_id={application_id}"

Response

[
  {
    "id": 536,
    "criteria_type": "evaluate",
    "query": null,
    "input_1": "TOEIC",
    "input_2": null,
    "metric": "TOEIC grade",
    "value": "500",
    "operator": "higher",
    "expected_duration": null,
    "duration_unit": null,
    "question_eval": null,
    "coefficient": null,
    "archived": true,
    "created_at": "2024-10-30T00:00:00.000Z",
    "status": null,
    "agg_job_id": "06ac74b6-cc0d-4a65-88a6-227decf81a30",
    "mandatory": false,
    "section": 1729782567464,
    "criteria_result": [
      {
        "id": 1530,
        "criteria_id": 536,
        "result": false,
        "evaluated_at": null,
        "score": 100,
        "score_justification": "The total TOEIC score of 930 is higher than 500, thus meeting the criterion.",
        "citations": [
          "TOTAL SCORE: 930"
        ],
        "status": "finished",
        "application_id": "3ca8e587-d6fd-41d4-9074-ac377f5dee29",
        "job_id": "06ac74b6-cc0d-4a65-88a6-227decf81a30",
        "section": 1729782567464,
        "confidence": 100,
        "confidence_justification": "The agent correctly extracted the TOEIC Total Score as 930, which is indeed higher than 500. This result satisfies the given criterion, and the cited section from the content supports the agent's claim."
      }
    ]
  }
]

GET/v1/evaluations/:id

Fetch a specific evaluation by ID

This endpoint allows you to retrieve a specific evaluation by providing its ID. The response includes details about the criteria results and the overall result of the evaluation.

Request

GET

/v1/evaluations/{id}

curl https://api.semantikmatch.com/v1/evaluations/1001 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": 536,
  "criteria_type": "evaluate",
  "query": null,
  "input_1": "TOEIC",
  "input_2": null,
  "metric": "TOEIC grade",
  "value": "500",
  "operator": "higher",
  "expected_duration": null,
  "duration_unit": null,
  "question_eval": null,
  "coefficient": null,
  "archived": true,
  "created_at": "2024-10-30T00:00:00.000Z",
  "status": null,
  "agg_job_id": "06ac74b6-cc0d-4a65-88a6-227decf81a30",
  "mandatory": false,
  "section": 1729782567464,
  "criteria_result": [
    {
      "id": 1530,
      "criteria_id": 536,
      "result": false,
      "evaluated_at": null,
      "score": 100,
      "score_justification": "The total TOEIC score of 930 is higher than 500, thus meeting the criterion.",
      "citations": [
        "TOTAL SCORE: 930"
      ],
      "status": "finished",
      "application_id": "3ca8e587-d6fd-41d4-9074-ac377f5dee29",
      "job_id": "06ac74b6-cc0d-4a65-88a6-227decf81a30",
      "section": 1729782567464,
      "confidence": 100,
      "confidence_justification": "The agent correctly extracted the TOEIC Total Score as 930, which is indeed higher than 500. This result satisfies the given criterion, and the cited section from the content supports the agent's claim."
    }
  ]
}

DELETE/v1/evaluations/:id

Delete a specific evaluation by ID

This endpoint allows you to delete a specific evaluation by its ID. When an evaluation is deleted, the system automatically re-runs the evaluation process for the associated application.

Request

DELETE

/v1/evaluations/{id}

curl -X DELETE https://api.semantikmatch.com/v1/evaluations/1001 \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Evaluation deleted. Re-evaluation process has been triggered."
}

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.