Criteria

Criteria in Semantikmatch are rules that are used to evaluate specific fields in forms. Criteria allow for automated assessments, such as checking the validity of documents or evaluating candidate responses. On this page, we'll dive into the different criteria endpoints you can use to manage criteria programmatically. We'll look at how to query, create, update, and delete criteria.

The criteria model

The criteria model contains information about the evaluation rules applied to form fields. Each criterion defines how a specific field should be evaluated (e.g., check validity, extract information).

Properties

Name
id
Type
string
Description
Unique identifier for the criteria.
Name
form_section
Type
string
Description
The form section where the criteria apply.
Name
field
Type
string
Description
The specific field the criteria evaluate.
Name
type
Type
string
Description
The type of evaluation (e.g., check validity, extract information).
Name
created_at
Type
timestamp
Description
Timestamp of when the criteria were created.
Name
query
Type
string
Description
Criteria Types: Extract, Match
The query string used to extract or match information.
Name
input_1
Type
string
Description
Criteria Types: All
The primary field within the form to be evaluated.
Name
input_2
Type
string
Description
Criteria Types: Match
The secondary field within the form to be matched.
Name
metric
Type
string
Description
Criteria Types: Evaluate, Hardskill/Tool/Sector, Language, Soft-Skill
The metric used for evaluation or assessment.
Name
value
Type
string
Description
Criteria Types: Evaluate, Hardskill/Tool/Sector
The value to compare against the metric.
Name
operator
Type
string
Description
Criteria Types: Evaluate
The operator used for comparison (e.g., higher, lower).
Name
question_eval
Type
string
Description
Criteria Types: Open Questions
The evaluation grid for open questions.
Name
expected_duration
Type
string
Description
Criteria Types: Experience
The expected duration for experience evaluation.
Name
duration_unit
Type
string
Description
Criteria Types: Experience
The unit of time for the expected duration (e.g., months, years).

Criteria Types

Semantikmatch supports several types of criteria, each with a specific purpose. Here are the available criteria types:

Note: The arguments input_1 and input_2 always represent a field within the form. For more details on the form structure, please refer to the Form Endpoint Documentation.

1. Extract

Extract specific information from a document.

Fields: query, input_1 (must be in input list).
Example:

{ "criteria_type": "extract", "criteria_fields": { "query": "first name", "input_1": "passport" } }

2. Validity

Check if a document is still valid.

Fields: input_1 (must be in input list).
Example:

{ "criteria_type": "validity", "criteria_fields": { "input_1": "passport" } }

3. Evaluate

Compare a metric against a value.

Fields: input_1 (must be in input list), metric, value, operator.
Example:

{ "criteria_type": "evaluate", "criteria_fields": { "input_1": "TOEIC score report", "metric": "TOEIC grade", "value": "900", "operator": "higher" } }

4. Match

Verify if a value matches across two documents.

Fields: query, input_1, input_2 (both must be in input list).
Example:

{ "criteria_type": "match", "criteria_fields": { "query": "first name", "input_1": "passport", "input_2": "driver's license" } }

5. Open Questions

Evaluate a response using an evaluation grid.

Fields: input_1 (must be in input list), question_eval.
Example:

{ "criteria_type": "open_questions", "criteria_fields": { "input_1": "response to motivation question", "question_eval": "eval: if well-articulated, score: 100; if somewhat relevant, score: 50; if not relevant, score: 0" } }

6. Hardskill/Tool/Sector

Assess specific skills or tools.

Fields: input_1 (must be in input list), metric, value.
Example:

{ "criteria_type": "hardskill/tool/sector", "criteria_fields": { "input_1": "resume", "metric": "Python programming", "value": "Python" } }

7. Experience

Evaluate professional experience duration.

Fields: input_1 (must be in input list), metric, expected_duration, duration_unit.
Example:

{ "criteria_type": "experience", "criteria_fields": { "input_1": "CV", "metric": "developer", "expected_duration": "60", "duration_unit": "months" } }

8. Language

Assess language proficiency.

Fields: input_1 (must be in input list), metric.
Example:

{ "criteria_type": "language", "criteria_fields": { "input_1": "resume", "metric": "English" } }

9. Soft-Skill

Evaluate soft skills.

Fields: input_1 (must be in input list), metric.
Example:

{ "criteria_type": "soft-skill", "criteria_fields": { "input_1": "video response", "metric": "communication skills" } }

POST/v1/criteria/generate

Generate criteria

This endpoint allows you to generate criteria based on a job ID and a query.

Request Body

Content-Type: application/json

Schema:

{
  "jobId": "string",
  "query": "string"
}

Required:
- jobId: The ID of the job.
- query: The query string for generating criteria.

API Specifications

Endpoint: /v1/criteria/generate
Method: POST
Responses:
- 200: Criteria generated successfully.
- 400: Invalid input format.
- 500: Failed to generate criteria.

Schema

Response:

{
  "result": {
    "id": "101",
    "form_section": "Inscription",
    "field": "Upload your ID",
    "type": "Validity",
    "created_at": 162233200
  }
}

Request

POST

/v1/criteria/generate

curl -X POST https://api.semantikmatch.com/v1/criteria/generate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"jobId": "12345", "query": "example query"}'

Response

{
  "result": {
    "id": "101",
    "form_section": "Inscription",
    "field": "Upload your ID",
    "type": "Validity",
    "created_at": 162233200
  }
}

GET/v1/criteria

List all criteria

This endpoint allows you to retrieve a paginated list of all your criteria. By default, a maximum of ten criteria are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of criteria returned.
Name
section
Type
string
Description
Filter by section.
Name
criteria_type
Type
string
Description
Filter by criteria type.
Name
input_1
Type
string
Description
Filter by input_1.
Name
input_2
Type
string
Description
Filter by input_2.
Name
status
Type
string
Description
Filter by status.
Name
expected_duration
Type
string
Description
Filter by expected duration.
Name
mandatory
Type
boolean
Description
Filter by mandatory status.

API Specifications

Endpoint: /v1/criteria
Method: GET
Responses:
- 200: List of criteria.
- 500: Failed to fetch criteria.

Schema

Response:

{
  "has_more": false,
  "data": [
    {
      "id": "101",
      "form_section": "Inscription",
      "field": "Upload your ID",
      "type": "Validity",
      "created_at": 162233200
    },
    {
      "id": "102",
      "form_section": "Admission",
      "field": "Upload your Transcript",
      "type": "Extract",
      "created_at": 162233201
    }
  ]
}

Request

GET

/v1/criteria

curl -G https://api.semantikmatch.com/v1/criteria \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "101",
      "form_section": "Inscription",
      "field": "Upload your ID",
      "type": "Validity",
      "created_at": 162233200
    },
    {
      "id": "102",
      "form_section": "Admission",
      "field": "Upload your Transcript",
      "type": "Extract",
      "created_at": 162233201
    }
  ]
}

GET/v1/criteria/:id

Retrieve a criterion

This endpoint allows you to retrieve a specific criterion by providing its ID. The response includes all details about the criteria.

API Specifications

Endpoint: /v1/criteria/{id}
Method: GET
Parameters:
- id: (required) ID of the criterion to retrieve.
Responses:
- 200: Criterion details.
- 404: Criterion not found.
- 500: Failed to fetch criterion.

Schema

Response:

{
  "id": "101",
  "form_section": "Inscription",
  "field": "Upload your ID",
  "type": "Validity",
  "created_at": 162233200
}

Request

GET

/v1/criteria/{id}

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

Response

{
  "id": "101",
  "form_section": "Inscription",
  "field": "Upload your ID",
  "type": "Validity",
  "created_at": 162233200
}

DELETE/v1/criteria/:id

Delete a criterion

This endpoint allows you to delete a specific criterion by its ID. Once deleted, the criterion will no longer apply to the associated form field.

API Specifications

Endpoint: /v1/criteria/{id}
Method: DELETE
Parameters:
- id: (required) ID of the criterion to delete.
Responses:
- 200: Criterion deleted successfully.
- 404: Criterion not found.
- 500: Failed to delete criterion.

Schema

Response:

{
  "message": "Criterion deleted successfully"
}

Request

DELETE

/v1/criteria/{id}

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

Response

{
  "message": "Criterion deleted successfully"
}