Introduction

The Vort Partner API is for ATS vendors who embed Vort’s AI candidate matching inside their own product. You build the screens; Vort supplies the matching, the candidates, and every sentence the recruiter reads about them. The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are used as described in RFC 2119.

Quickstart

Take one customer from activation code to a reported decision with curl, Node.js, Python or PHP.

Integration flow

The eight steps of every integration, from connecting a customer to receiving webhooks.

UI specification

The screens you build, what you may customize, and what is fixed.

API reference

Every endpoint and webhook, generated from the OpenAPI 3.1 document.

Base URLs

Environment	Base URL	Keys
Sandbox	`https://vort-partner-api.vercel.app/sandbox/v1`	Sandbox partner key, issued by Vort at onboarding.
Production	Issued at go-live.	Production partner key, issued after certification passes.

Every endpoint is {BASE_URL}/v1/<path>. In the sandbox, POST /runs is POST https://vort-partner-api.vercel.app/sandbox/v1/runs. Keep the base URL in configuration so it can change without a release, and do not derive it from anything else.

Division of responsibility

You (the partner) own	Vort owns
The screens, their colors and their fonts.	The layout rules in the UI specification.
Your server, which holds all Vort credentials.	Matching, candidates, verdicts, evidence.
Mapping your customers, users and jobs to external ids.	Every text the recruiter reads about a run: notices, validation messages, suggestions, prices, verdict reasons.
Sending every recruiter decision back to Vort.	Pricing and credits.

The content rule is strict. Notices, requirement messages, suggestions, evidence and prices are rendered from the API payload. Your UI MUST NOT rewrite, shorten, translate or replace them with your own copy. If a sentence reads wrong, report it to Vort with the run_id and Vort fixes it for every partner at once.

The flow in 8 steps

 Customer admin            Your frontend             Your server                     Vort
 ──────────────            ─────────────             ───────────                     ────
 1. receives VORT-XXXX-XXXX from Vort
    pastes it  ──────────▶ "Connect Vort" form ────▶ POST /activations/redeem ─────▶ 200 {org_token}
                                                     stores org_token (server side)
 2.                                                  POST /users   (each recruiter) ▶ 200 {user_id}
 3.                        job screen          ────▶ POST /jobs                    ─▶ 200 {job_id}
 4.                        requirements editor ────▶ POST /runs                    ─▶ 202 {run_id} | 422
 5.                        results screen      ◀──── GET /runs/{run_id}  (poll)    ◀─ progress, notices, candidates
                                                     (+ webhook run_completed / run_failed)
 6.                        "Reveal contact"    ────▶ POST /runs/{id}/candidates/{cid}/reveal ▶ email, phone, credits
 7.                        shortlist / reject  ────▶ POST /runs/{id}/decisions    ─▶ 200 {accepted, duplicates}
 8.                                                  receives webhooks, verifies x-vort-signature

Each step is described in Integration flow. The Quickstart walks through steps 1 to 7 against the sandbox.

Authentication at a glance

Two secrets, both server-side only: your partner API key (x-partner-key, on every request) and one org token per connected customer (x-vort-org, on every request except POST /activations/redeem).

Every call is server-to-server. A Vort key or org token MUST NOT reach a browser, a mobile app, a log line visible to customers, a URL, or a frontend bundle. Details, rotation and the connect flow are in Authentication.

Languages

Vort’s content is available in Hebrew (he) and English (en). Send x-vort-lang: he|en to choose the language of notices and messages for a request; without it Vort uses your partner default (Hebrew unless agreed otherwise). Requirement validation issues carry both languages (message_he, message_en); show the one matching the recruiter’s UI language. When the language is Hebrew your screens MUST render right-to-left.

Versioning policy

The version is in the path: {BASE_URL}/v1/....
Within v1, Vort makes additive changes only: new endpoints, new optional request fields, new response fields, new notice codes, new webhook events, new error codes on existing HTTP statuses. These are non-breaking.
Breaking changes (removing or renaming a field, changing a type or meaning) ship only as /v2, announced in advance, with an overlap period (agreed with partners) during which /v1 keeps working.

Because changes within v1 are additive, your client MUST:

ignore unknown fields in every response and webhook body;
render a notice with an unknown code generically (see Notices);
ignore webhook events it does not know, still answering 2xx;
handle an unknown error code by its HTTP status.

Changes are listed in the Changelog.

Environments

You develop and certify against the sandbox: a real deployment on real search results, with synthetic contact details, masked candidate names until the data processing annex is signed, and certification fixtures that return fixed payloads (see Sandbox). Production keys and the production base URL are issued after certification passes. Keep the base URL, the partner key and the org tokens in per-environment configuration.

Data handling

Candidate data you receive from the API (names, titles, employers, locations, evidence, and revealed contact details) is personal data. Its processing is governed by the Data Processing Annex to the partnership agreement.

Placeholder, to be agreed. The annex will fix: retention periods for candidate data and revealed contact details on your side; propagation of deletion and correction requests (Vort to partner and partner to Vort) and the deadline for each; sub-processors; breach notification; and the lawful basis for contacting candidates under Israeli law. Until the annex is signed, do not copy candidate data outside the customer’s own workspace in your product.

Support

Always include the run_id when you contact Vort about a run. It is returned by POST /runs, echoed in every run response and every webhook, and it MUST be visible to the recruiter in your UI so that the recruiter can quote it to you and you can quote it to Vort.

For API errors, also include the request time (UTC), the HTTP method and route, the status and the error code.

Never send Vort an org token or API key. The first 12 characters of the key (for example vpk_live_3f9) are enough to identify it.

Get started

Build the integration

Quickstart

Integration flow

UI specification

API reference

Base URLs

Division of responsibility

The flow in 8 steps

Authentication at a glance

Languages

Versioning policy

Environments

Data handling

Support

Quickstart

Integration flow

UI specification

API reference

​Base URLs

​Division of responsibility

​The flow in 8 steps

​Authentication at a glance

​Languages

​Versioning policy

​Environments

​Data handling

​Support

Base URLs

Division of responsibility

The flow in 8 steps

Authentication at a glance

Languages

Versioning policy

Environments

Data handling

Support