> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vort-sourcing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> What the Vort Partner API does, how the pieces fit, and the rules every integration follows.

export const SANDBOX_BASE = "https://vort-partner-api.vercel.app/sandbox";

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](https://www.rfc-editor.org/rfc/rfc2119).

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Take one customer from activation code to a reported decision with `curl`, Node.js, Python or PHP.
  </Card>

  <Card title="Integration flow" icon="workflow" href="/integration-flow">
    The eight steps of every integration, from connecting a customer to receiving webhooks.
  </Card>

  <Card title="UI specification" icon="layout-panel-top" href="/ui-specification">
    The screens you build, what you may customize, and what is fixed.
  </Card>

  <Card title="API reference" icon="square-terminal" href="/api-reference/introduction">
    Every endpoint and webhook, generated from the OpenAPI 3.1 document.
  </Card>
</Columns>

## Base URLs

| Environment | Base URL | Keys |
| - | - | - |
| Sandbox | <code>{SANDBOX_BASE}/v1</code> | Sandbox partner key, issued by Vort at onboarding. |
| Production | Issued at go-live. | Production partner key, issued after [certification](/certification) passes. |

Every endpoint is `{BASE_URL}/v1/<path>`. In the sandbox, `POST /runs` is <code>POST {SANDBOX_BASE}/v1/runs</code>. 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](/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. |

<Warning>
  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.
</Warning>

## The flow in 8 steps

```text theme={null}
 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](/integration-flow). The [Quickstart](/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`).

<Warning>
  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](/authentication).
</Warning>

## 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.

<Info>
  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](/notices));
  * ignore webhook events it does not know, still answering `2xx`;
  * handle an unknown `error` code by its HTTP status.
</Info>

Changes are listed in the [Changelog](/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](/sandbox)). **Production** keys and the production base URL are issued after [certification](/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.

<Note>
  **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.
</Note>

## Support

<Info>
  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.
</Info>

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

<Warning>
  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.
</Warning>