Match CVs to a job

Match one or more candidate CVs against a job description using AI-powered scoring. Configure optional weights to prioritize specific dimensions such as experience, hard skills, soft skills, or education. The sum of all weights must not exceed 1.0. Billable — charges the job_matching action once per match request. See GET /tokens/costs for live pricing.

POST /match

Match CVs to a job

cURL

curl --request POST \
  --url https://api-service.fribl.co/api/v1/match \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "jobId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "candidatesIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "topK": 2,
  "weights": {
    "experience": 0.25,
    "hardSkills": 0.25,
    "softSkills": 0.25,
    "education": 0.25
  },
  "cache": true
}
'

200

{
  "message": "Match result",
  "length": 123,
  "data": [
    [
      {
        "score_meta": {
          "education": 123,
          "hard_skills": 123,
          "soft_skills": 123,
          "experience": 123
        },
        "score_dict": {
          "education": {},
          "hard_skills": {},
          "soft_skills": {},
          "experience": {}
        },
        "summary_score": 123,
        "final_score": 123,
        "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ]
  ]
}

Authorizations

x-api-key · string · header · required

API key in UUID format. Include this header with every authenticated request.

Body

application/json

Request body for matching CVs to a job.

jobId · string<uuid> · required

Unique identifier of the job to match against.

candidatesIds · string<uuid>[] · required

List of CV identifiers to match against the job.

topK · integer · required

Maximum number of top-scoring candidates to return.

Required range: x >= 1

weights · object

Custom weights for each scoring dimension. The sum of all weights must not exceed 1.0. If omitted, equal weights are applied.

Show child attributes

cache · boolean

Whether to cache the match results for later retrieval.

Response

200

application/json

Match results with scored candidates.

message · string · required

Example:

"Match result"

length · integer · required

Number of result sets returned.

data · object[][] · required

Nested array of match results. Each inner array contains scored candidates for a match operation.

Show child attributes