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" } }
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request, invalid_header, invalid_json | An id, header or JSON body is not valid. |
| 401 | invalid_key, key_revoked | The key is missing, unknown or revoked. |
| 403 | scope_not_allowed, ip_not_allowed, environment_suspended | The key may not call this endpoint, or not from this address. |
| 404 | not_found | The document is not in that index, or the route does not exist. |
| 411, 413 | length_required, body_too_large | Send a Content-Length; the file is over the size limit. |
| 422 | invalid_fields, invalid_request, no_document_text | A field is unknown, missing or invalid, or the file holds no CV or job text. |
| 503 | busy, model_unavailable | A scanned or old-format file needs more time, or scoring is briefly unavailable; send it again in a minute. |
| 502, 504 | upstream_unavailable, upstream_timeout | The 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.
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" }
}
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": [] }
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" }
}
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.
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 }
Search
Lists the CVs in your indexes that pass a filter, with paging. A value the filter cannot use, such as an unknown language code, is listed back in ignored_filters.
{
"indexes": ["candidates"],
"filters": { "tags": ["source-website"], "skills": ["Python"], "languages": ["nl"] },
"offset": 0,
"limit": 50
}
{ "results": [ { "index": "candidates", "id": "cv-1093" } ], "total": 1, "ignored_filters": [] }
| Filter | Values | Keeps CVs with |
|---|---|---|
ids | list of ids | Only these documents. |
tags, tags_match | "any" or "all" | Tags set when the CV was stored. |
skills, skills_match | "any" or "all" | Skills, matched as whole words in any language the CV uses. |
job_titles, job_titles_match | current_titles_only | Job titles held, or held now. |
employers | current_employer_only | Employers, or the current one. |
languages, languages_match | ISO codes or names | Languages the candidate speaks. |
education_levels | secondary, vocational, bachelor, master, doctorate | An education entry at one of these levels. |
months_experience | { "min", "max" } | Total months of work experience. |
management_level | individual, lead, manager, director | Current level; director also matches executives. |
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.
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.
- Export the index and document ids, tags and files you already have; our migration tool reads them from your database.
- 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.
- Point your application's base URL at AI Matcher and use your new key.
- 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.