Embeddable Candidate Matching API: Builder's Guide

An embeddable candidate matching API is an HTTP endpoint you send a job and one or more candidate profiles to, and get back a ranked, scored result your own product renders. The word that matters is embeddable: you are not buying a matching product a recruiter logs into, you are calling a service so the matching happens inside the ATS, CRM, or recruitment platform you already ship. The response comes back as JSON, the interchange format standardized as IETF RFC 8259, so your code can store it, sort it, and show it however your product needs.

This is a different job from two things it is often confused with. It is not parsing: turning a raw resume or CV into structured fields is covered in the CV parsing API guide and the resume parser API guide, and parsing is the input that feeds a matcher, not the match itself. It is also not connecting to a third-party ATS: reading and writing data in a system a customer already runs is the subject of the applicant tracking system API guide. This guide is about embedding the matching logic itself: scoring, ranking, latency, and the schema contract.

The reason builders reach for this now is that intelligent matching has become an expected feature rather than a differentiator. In its 2025 Talent Trends research, a survey of 2,040 HR professionals, SHRM found that 51 percent of organizations that use AI in HR apply it to recruiting, with common uses including screening resumes and automating candidate searches, per SHRM's 2025 Talent Trends report. The minimum viable integration is a single call: POST a job description and a set of candidates, and receive a ranked list with a score and an explanation for each. Everything else in this guide is about doing that call well.

The first design decision is how the score is computed. A keyword or boolean filter is exact match. It asks whether the candidate text contains the terms in the job, so a candidate who wrote "frontend development" is invisible to a query for "React" even though they are a strong fit. That is not a tuning problem, it is the wrong model for the question you are asking.

Semantic matching uses the vector space model instead. You represent the job and each candidate as vectors, then score their similarity by the cosine of the angle between them, so a higher cosine means a closer match. This is the standard information-retrieval approach set out in Manning, Raghavan, and Schutze's Introduction to Information Retrieval (Cambridge University Press, 2008). Because it measures closeness in meaning rather than shared tokens, it ranks a candidate by how near they sit to the role, not by whether they used the same words.

What puts the meaning into those vectors is contextual embeddings. Models such as BERT, introduced by Devlin and colleagues in BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding (NAACL 2019), encode a term from the words around it, so "React" lands near "frontend development" in the vector space without any shared token. That is what lets semantic skill matching understand that React relates to frontend and that Python relates to data science, and it is the model behind the RecruitAI Suite matcher.

A better model is only useful if it returns in time to be used. Response time here is not a vanity metric, it is a usability constraint. Robert B. Miller's 1968 study Response time in man-computer conversational transactions established that response time is a primary determinant of whether an interactive transaction stays usable, and that a short response is what keeps a user's train of thought unbroken. A matching call rendered inside a live ATS screen competes with that expectation, and the network round trip and page render both eat into the budget, so the scoring step itself has to stay quick.

Hitting that target across a large candidate pool is where the real engineering lives. Scoring a job against every candidate one at a time is a brute-force comparison whose cost grows linearly with the size of the database, and that does not hold sub-second once you have millions of profiles. The standard answer is approximate nearest neighbor search. Malkov and Yashunin's Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs (IEEE Transactions on Pattern Analysis and Machine Intelligence, 2020) describes an index that finds the nearest vectors with logarithmic-scaling complexity instead of a full linear scan.

The contract is what your product actually integrates against, so judge a matching API on its request and response shape before anything else. The request carries a job and one or more candidates. The response should be a ranked array where each entry has a match score, its position in the ranking, and explanation fields that say why the score was assigned. All of it travels as JSON per RFC 8259, so if the API hands you a bare number with no structure around it, you have less to build on than you think.

The transport behavior matters just as much as the payload. HTTP semantics are defined in IETF RFC 9110, published in 2022, which sets out the status-code classes you should expect: 2xx for a successful match, 4xx when your request is malformed, and 5xx when the service itself fails. RFC 9110 also defines safe and idempotent methods and notes that some requests can be automatically retried by a client after a connection failure. A scoring request has no side effects, so design and document it so a client can safely retry it, and return status codes that tell the caller whether to fix the request or retry the call.

Explanation fields are not a nicety, they are what keeps the feature compliant. A matching API only returns scores, but the moment those scores rank, shortlist, or filter candidates, the feature becomes a selection tool, and selection tools are regulated. In the EU, AI intended for the recruitment or selection of candidates is classified as high-risk under Annex III of the EU AI Act, Regulation (EU) 2024/1689, and GDPR Article 22 gives people the right not to be subject to a decision based solely on automated processing that significantly affects them, with recruitment named as an example.

The US adds its own obligations. New York City's Local Law 144 requires that an automated employment decision tool be subject to an independent bias audit within one year of its use and that the audit be made publicly available, and the NYC Department of Consumer and Worker Protection began enforcement on 5 July 2023, per its automated employment decision tools guidance. Underneath that sits the long-standing four-fifths rule in 29 CFR 1607.4, which treats a selection rate for any race, sex, or ethnic group that is less than four-fifths, or 80 percent, of the rate for the highest group as evidence of adverse impact.

Building matching yourself means owning contextual embedding models, a vector index tuned for sub-second approximate search, a scoring and explanation layer, and the ongoing work of keeping all of it accurate, before you ship a single customer-facing feature. For most teams that is the wrong place to spend engineering time. The pragmatic path is to embed a matching layer through an API and keep your effort on your own product.

RecruitAI Suite provides that layer. The Candidate Matching API scores and ranks candidates against a role with semantic matching rather than keyword search, and returns explainable match scores your product can display and audit. Where you need the reverse direction, matching open jobs to a given candidate, the Job Matching API covers it, and the structured input both rely on comes from the Resume Parser API. ATS and CRM teams can see how the pieces slot together on the ATS vendors page.

If you want to try it against your own jobs and candidates, or walk through how it would embed in your platform, you can book a demo and we will set you up. You can also browse the full product list to see how the matching API fits alongside the rest of the suite.