AI Matcher API docs Get a pilot key

API documentation

AI Matcher is a REST API with JSON bodies. You parse CVs and job ads, store them in indexes you name, and rank candidates for a job or jobs for a candidate. Every route below lives under your region's base URL; for the EU region that is https://eu.api.kondiq.com/api/v1.

https://eu.api.kondiq.com/api/v1/…

An index is a named collection, for example one per organisation for its CVs and one for its jobs. A document id is your own id for a CV or job inside an index. Ids use letters, digits, - and _, up to 128 characters.

Authentication

Send your key in the X-Api-Key header on every request. A key belongs to one environment (for example test or production): it only ever sees that environment's indexes. Each key can be limited to some endpoints (scopes) and to the IP addresses you list.

curl https://eu.api.kondiq.com/api/v1/search \
  -H "X-Api-Key: aim_live_…" \
  -H "Content-Type: application/json" \
  -d '{"indexes": ["candidates"]}'

Responses and errors

A successful call answers with its data as plain JSON. A failed call answers with an HTTP error status and an error object; code is stable and safe to branch on, message is for people.

{ "error": { "code": "not_found", "message": "Document not found" } }
StatusCodeMeaning
400invalid_request, invalid_header, invalid_jsonAn id, header or JSON body is not valid.
401invalid_key, key_revokedThe key is missing, unknown or revoked.
403scope_not_allowed, ip_not_allowed, environment_suspendedThe key may not call this endpoint, or not from this address.
404not_foundThe document is not in that index, or the route does not exist.
411, 413length_required, body_too_largeSend a Content-Length; the file is over the size limit.
422invalid_fields, invalid_request, no_document_textA field is unknown, missing or invalid, or the file holds no CV or job text.
503busy, model_unavailableA scanned or old-format file needs more time, or scoring is briefly unavailable; send it again in a minute.
502, 504upstream_unavailable, upstream_timeoutThe service did not answer in time; send the call again.

Files and limits

  • Formats: PDF, DOCX, DOC, RTF, ODT, TXT, and PNG, JPEG, TIFF, BMP or WEBP images (read with OCR).
  • Size: up to 10 MB per file, sent as base64 in file; PDFs up to 30 pages.
  • Search: up to 50 indexes and 100 results per page. Match: up to 50 indexes and 200 results.
  • Tags: up to 500 per document.
  • Unknown fields are refused with 422, so a misspelt filter never widens a result.
POST /cvs/parse

Parse a CV

Returns the structured CV. Add index and id to store it in the same call, ready for search and match; tags are stored with it. Sentences that try to instruct the AI are removed and reported in warnings. Values that are not in the document are left empty, never invented.

{
  "file": "JVBERi0xLjQK…",
  "index": "candidates",
  "id": "cv-1093",
  "tags": ["source-website"]
}
{
  "cv": {
    "contact": { "name": "Jan Peeters", "email": "jan.peeters@example.com", "phone": "+32 470 12 34 56", "location": "Antwerp", "links": [] },
    "summary": null,
    "positions": [ { "title": "Backend Developer", "employer": "Example NV", "start": "2020-01", "end": null, "is_current": true, "description": "…" } ],
    "education": [ { "degree": "MSc Computer Science", "level": "master", "field": "Computer Science", "institution": "KU Leuven", "end": "2019" } ],
    "skills": ["Python", "PostgreSQL"],
    "certifications": [],
    "languages": [ { "language": "Dutch", "level": "native" }, { "language": "English", "level": "fluent" } ],
    "industries": ["Software"],
    "management_level": "individual",
    "executive_type": null,
    "text": "Jan Peeters …"
  },
  "warnings": [],
  "indexed": { "index": "candidates", "id": "cv-1093" }
}
POST /cvs/preview

Quick preview

For a create-candidate form: answers with the name, email, phone and location in seconds, and starts the full parse in the background. Send the same file to /cvs/parse within 30 minutes, with index and id when the recruiter saves, and it answers from that work. The two calls count as one parse. A preview never stores anything.

{ "file": "JVBERi0xLjQK…" }
{ "contact": { "name": "Jan Peeters", "email": "jan.peeters@example.com", "phone": "+32 470 12 34 56", "location": "Antwerp", "links": [] }, "warnings": [] }
POST /jobs/parse

Parse a job

Reads a job ad, sent as file or as text, and returns its title, required and preferred skills, languages, education and experience. With index and id the job is stored, and AI fit scoring starts against the CV indexes in match_into.

{
  "text": "We are looking for a Python developer…",
  "index": "jobs",
  "id": "job-42",
  "match_into": ["candidates"]
}
{
  "job": {
    "title": "Python Developer",
    "alternative_titles": ["Backend Developer"],
    "required_skills": ["Python", "PostgreSQL"],
    "preferred_skills": ["Docker"],
    "required_languages": ["Dutch"],
    "required_certifications": [],
    "education_level": "bachelor",
    "industries": ["Software"],
    "management_level": "individual",
    "executive_type": null,
    "min_years_experience": 3
  },
  "indexed": { "index": "jobs", "id": "job-42" }
}
PUT /indexes/{index}/cvs/{id}

Store parsed data

Stores a CV or job you already have (for example one a recruiter corrected) without parsing it again. The body holds the same fields the parse calls return. Storing the same id again replaces it; unchanged CVs are not scored again.

{ "cv": { "positions": [ … ], "skills": [ … ], … }, "tags": ["reviewed"] }

For a job, PUT /indexes/{index}/jobs/{id} takes job, the ad's own text in ad_text (it ranks people better than the parsed fields) and match_into.

PATCH /indexes/{index}/cvs/{id}/tags

Update tags

mode is add (keep the current tags) or replace (the default). Tags only change filtering, so scores stay.

{ "tags": ["reviewed"], "mode": "add" }
DELETE /indexes/{index}/documents/{id}

Delete a document

Removes the CV or job with its scores and any queued work. DELETE /indexes/{index} removes a whole index. A candidate's GDPR erase across every index of your environment is done from the customer portal, which keeps a receipt.

{ "deleted": true }
POST /indexes/{index}/documents/{id}/matches

Match

Ranks the CVs in indexes for a stored job, or the jobs for a stored CV. weights decide how much each category counts (job_titles, skills, education, languages, certifications, industries, management_level, executive_type); leave them at titles and skills for the overall score. The same filters as search apply when a job looks for people.

{
  "indexes": ["candidates"],
  "limit": 20,
  "weights": { "job_titles": 0.5, "skills": 0.5 },
  "filters": { "tags": ["available"] }
}
{
  "ranked_by": "ai_fit",
  "total": 1240,
  "weights": { "job_titles": 0.5, "skills": 0.5, "education": 0, … },
  "ignored_filters": [],
  "matches": [
    {
      "index": "candidates",
      "id": "cv-1093",
      "score": 92,
      "formula_score": 81,
      "ai_fit": { "score": 92, "categories": { "job_titles": 95, "skills": 90, "languages": 85 } },
      "categories": {
        "skills": { "score": 88, "has_data": true, "found": [ { "skill": "Python", "current": true } ], "missing": ["Kubernetes"] },
        "job_titles": { "score": 95, "has_data": true, "found": [ { "title": "Backend Developer", "matches": "Python Developer", "current": true } ], "missing": [] }
      }
    }
  ]
}

ranked_by tells you which score ranked the list. formula answers at once from stored vectors; once every candidate of the job has an AI score, the list answers with ai_fit. The two are never mixed in one list, and score always holds the score the list was ranked by. categories show which skills, titles and languages were found or missing.

GET /indexes/{index}/jobs/{id}/scoring

Scoring progress

How far AI fit scoring of a job has come.

{ "scored": 812, "total": 1240, "match_into": ["candidates"], "queued": 3, "worker_running": true }

Migrating your data

Moving from the parser you use today takes four steps, and your application keeps running throughout. If your application already speaks the request shapes of a common recruitment parser, AI Matcher can answer in those shapes too, so the switch is a new base URL; we share that reference with your pilot key.

  1. Export the index and document ids, tags and files you already have; our migration tool reads them from your database.
  2. Run the tool against your test environment: it parses every CV and job into the same indexes and ids, and can be stopped and resumed.
  3. Point your application's base URL at AI Matcher and use your new key.
  4. Run the tool once more to catch up on what changed during the switch. To go back, change the base URL back.

We run the migration with you during the pilot. Get in touch to plan it.