Scorecards

Scorecards define how candidate applications are scored in Semantikmatch. They specify conditions to evaluate and assign points based on criteria results. On this page, we'll explore the different scorecard endpoints you can use to manage scoring rules programmatically.

The Scorecard Model

The scorecard model contains all the information about scoring rules, including conditions, values to compare, and points to assign.

Example Scorecard

{
  "id": "12",
  "criteria_id": "74",
  "description": "Value equals 100 (-2 points)",
  "condition": "EQ",
  "value_to_compare": "100",
  "scoring": -2,
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "created_at": "2025-05-05T08:12:47.505Z",
  "comparison_source": "payload"
}

Properties

Name
id
Type
string
Description
Unique identifier for the scorecard.
Name
criteria_id
Type
string
Description
Reference to the criteria this scorecard is associated with.
Name
description
Type
string
Description
Human-readable description of this scoring rule.
Name
condition
Type
string
Description
The condition for scoring (e.g., "EQ", "HigherThan", "LowerThan").
Name
value_to_compare
Type
string
Description
The value to compare against.
Name
scoring
Type
number
Description
Points to assign when the condition is met.
Name
job_id
Type
string
Description
The associated job ID.
Name
created_at
Type
string
Description
ISO timestamp of when the scorecard was created.
Name
comparison_source
Type
string
Description
Source field for comparison (default: "payload").

Condition Types

Name
EQ
Type
string
Description
Equals - Value must match exactly.
Name
HigherThan
Type
string
Description
Higher Than - Value must be greater than the comparison value.
Name
LowerThan
Type
string
Description
Lower Than - Value must be less than the comparison value.
Name
HigherOrEqual
Type
string
Description
Higher Or Equal - Value must be greater than or equal to the comparison value.
Name
LowerOrEqual
Type
string
Description
Lower Or Equal - Value must be less than or equal to the comparison value.
Name
Between
Type
string
Description
Between - Value must be between two comparison values.
Name
NotBetween
Type
string
Description
Not Between - Value must not be between two comparison values.
Name
In
Type
string
Description
In - Value must be in a list of comparison values.
Name
NotIn
Type
string
Description
Not In - Value must not be in a list of comparison values.
Name
NonNumeric
Type
string
Description
Non-Numeric - Specialized condition for text-based comparisons.

GET/api/scorecards/job/{jobId}

Get Scorecards for a Job

This endpoint allows you to retrieve all scorecards for a specific job.

Parameters

Name
jobId
Type
string
Description
The job ID to retrieve scorecards for.

Get Scorecards for a Job

curl "https://api.semantikmatch.com/api/scorecards/job/e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": "12",
    "criteria_id": "74",
    "description": "Value equals 100 (-2 points)",
    "condition": "EQ",
    "value_to_compare": "100",
    "scoring": -2,
    "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
    "created_at": "2025-05-05T08:12:47.505Z",
    "comparison_source": "payload",
    "criteria": {
      "id": "74",
      "custom_name": "Low Performance Check"
    }
  },
  {
    "id": "14",
    "criteria_id": "71",
    "description": "Value > 0 (+2 points)",
    "condition": "HigherThan",
    "value_to_compare": "0",
    "scoring": 2,
    "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
    "created_at": "2025-05-05T08:12:47.505Z",
    "comparison_source": "payload",
    "criteria": {
      "id": "71",
      "custom_name": "Strong Performance Count"
    }
  }
]

GET/api/scorecards/{scorecardId}

Get Scorecard by ID

This endpoint allows you to retrieve a specific scorecard by its ID.

Parameters

Name
scorecardId
Type
string
Description
The scorecard ID to retrieve.

Get Scorecard by ID

curl "https://api.semantikmatch.com/api/scorecards/12" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "12",
  "criteria_id": "74",
  "description": "Value equals 100 (-2 points)",
  "condition": "EQ",
  "value_to_compare": "100",
  "scoring": -2,
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "created_at": "2025-05-05T08:12:47.505Z",
  "comparison_source": "payload",
  "criteria": {
    "id": "74",
    "criteria_type": "evaluate",
    "query": "Check if the calculated percentages across all subjects indicate a failing grade below 50%.",
    "metric": "Grades",
    "value": "50",
    "operator": "lower",
    "custom_name": "Low Performance Check"
  }
}

POST/api/scorecards

Create a Scorecard

This endpoint allows you to create a new scorecard. The scorecard defines a scoring rule for evaluating applications.

Required Parameters

Name
condition
Type
string
Description
The condition for scoring (e.g., "EQ", "HigherThan").
Name
scoring
Type
number
Description
Points to assign when the condition is met.
Name
job_id
Type
string
Description
The job ID to associate this scorecard with.

Optional Parameters

Name
criteria_id
Type
string
Description
The criteria ID to associate this scorecard with.
Name
description
Type
string
Description
Human-readable description of this scoring rule.
Name
value_to_compare
Type
string
Description
The value to compare against.
Name
comparison_source
Type
string
Description
Source field for comparison (default: "payload").

Create a Scorecard

curl "https://api.semantikmatch.com/api/scorecards" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "criteria_id": "71",
  "description": "Value > 0 (+5 points)",
  "condition": "HigherThan",
  "value_to_compare": "0",
  "scoring": 5,
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "comparison_source": "payload"
}'

Response

{
  "id": "18",
  "criteria_id": "71",
  "description": "Value > 0 (+5 points)",
  "condition": "HigherThan",
  "value_to_compare": "0",
  "scoring": 5,
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "created_at": "2025-05-07T15:45:23.789Z",
  "comparison_source": "payload",
  "criteria": {
    "id": "71",
    "custom_name": "Strong Performance Count"
  }
}

PUT/api/scorecards/{scorecardId}

Update a Scorecard

This endpoint allows you to update an existing scorecard.

Parameters

Name
scorecardId
Type
string
Description
The scorecard ID to update.

Optional Update Fields

Name
criteria_id
Type
string
Description
The criteria ID to associate this scorecard with.
Name
description
Type
string
Description
Human-readable description of this scoring rule.
Name
condition
Type
string
Description
The condition for scoring (e.g., "EQ", "HigherThan").
Name
value_to_compare
Type
string
Description
The value to compare against.
Name
scoring
Type
number
Description
Points to assign when the condition is met.
Name
comparison_source
Type
string
Description
Source field for comparison.

Update a Scorecard

curl "https://api.semantikmatch.com/api/scorecards/12" \
  -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Value equals 100 (-5 points)",
  "scoring": -5
}'

Response

{
  "id": "12",
  "criteria_id": "74",
  "description": "Value equals 100 (-5 points)",
  "condition": "EQ",
  "value_to_compare": "100",
  "scoring": -5,
  "job_id": "e0395dae-e4b7-4b28-ae9c-52b5c6fc6b1c",
  "created_at": "2025-05-05T08:12:47.505Z",
  "updated_at": "2025-05-07T15:48:32.401Z",
  "comparison_source": "payload",
  "criteria": {
    "id": "74",
    "custom_name": "Low Performance Check"
  }
}

DELETE/api/scorecards/{scorecardId}

Delete a Scorecard

This endpoint allows you to delete a specific scorecard.

Parameters

Name
scorecardId
Type
string
Description
The scorecard ID to delete.

Delete a Scorecard

curl "https://api.semantikmatch.com/api/scorecards/12" \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

// No content (HTTP 204)