Pro vývojáře

Přihláška dovnitř. Evidence report ven.

REST API se dvěma režimy příjmu, webhooky a sandboxem, který se nikdy nedotkne živého zdroje. Všechno, co produkt umí, je dostupné přes API; rozhraní je jen jeden z jeho klientů.

Endpointy

Metoda a cesta	Scope	Co dělá
`POST /v1/applications`	`applications:write`	Přijme přihlášku, v jednom ze dvou režimů níž.
`GET /v1/applications/{id}`	`reports:read`	Stav přihlášky: waiting_confirmation, confirmed nebo checked.
`GET /v1/applications/{id}/claims`	`reports:read`	Tvrzení vytažená z životopisu, která čekají na potvrzení člověkem.
`POST /v1/applications/{id}/claims/confirm`	`applications:write`	Potvrdí tvrzení. Vyžaduje acting_user, takže je zapsaný člověk.
`POST /v1/applications/{id}/checks`	`applications:write`	Spustí kontrolu. Vyžaduje acting_user.
`GET /v1/applications/{id}/report`	`reports:read`	Report: tři bloky, u každého nálezu jeho původ.
`DELETE /v1/applications/{id}`	`applications:write`	Okamžitě smaže kandidáta.
`POST /v1/webhooks`	`webhooks:manage`	Zaregistruje endpoint a jednou vrátí jeho podpisový secret.
`GET /v1/webhooks`	`webhooks:manage`	Vypíše aktivní endpointy, bez secretů.
`DELETE /v1/webhooks/{id}`	`webhooks:manage`	Odvolá endpoint.

Autentizace je bearer klíč, cand_live_ nebo cand_test_, který nese scopes výše. Limit je 120 požadavků za minutu na organizaci, nad něj API odpovídá 429 s hlavičkou Retry-After.

Dvě cesty, kterými přihláška vstupuje

Strukturovaná data

Tvrzení, která už člověk zadal ve vašem ATS, přijdou jako JSON a zapíšou se rovnou jako potvrzená pod identitou v acting_user. Kontrola může běžet hned, protože za tvrzeními už člověk stojí.

Soubor životopisu

PDF do 10 MB přijde jako multipart form data. Tvrzení z něj vytažená čekají na potvrzení přes endpoint confirm: mezi extrakcí a kontrolou stojí člověk a vynucuje to databázový zámek, ne prosba v dokumentaci.

Strukturovaný příjem, celý požadavek

POST /v1/applications
Authorization: Bearer cand_test_...

{
  "acting_user": "recruiter@firma.cz",
  "positionTitle": "Backend Developer",
  "applicationReceivedAt": "2026-08-01",
  "externalRef": "ATS-1234",
  "email": "kandidat@example.com",
  "claims": [
    {
      "employerName": "Acme s.r.o.",
      "employerCountry": "CZ",
      "claimedDomain": "acme.cz",
      "periodStart": "2020-01-01",
      "periodEnd": "2022-01-01"
    }
  ]
}

Jak nás napojíte

Tři cesty a u každé je jasné, co pro ni potřebujete.

API

Přihláška vstupuje jako JSON nebo jako soubor. Odpověď nese nálezy se zdrojem, časem dotazu a verzí pravidla.

Popis volání je v tabulce výš.

Import z CSV

Když ATS nemá API nebo k němu nemáte přístup, nahrajete export. Sloupce se namapují jednou a další import už jede podle toho.

Formát exportu si nepředepisujeme, mapování je na naší straně.

Napište nám, jaké ATS používáte

Napište, v čem nábor vedete, a řekneme, jestli to jde přes API, přes export, nebo zatím vůbec.

Odpověď dostanete písemně, ne jako pozvánku na hovor.

Jak vypadá report

Tři bloky: mismatches, verified_without_finding a unverifiable. Každý nález nese větu česky i anglicky, doklad, adresu zdroje, čas dotazu, klíč pravidla a jeho verzi. Blok unverifiable je součást pravdy, ne chybový stav: říká, co ověřit nešlo a proč.

Žádná odpověď tohohle API nikdy neobsahuje skóre, riziko, pravděpodobnost ani doporučení. V kódu je test, který selže, kdyby se objevily.

Webhooky

Dnes jeden typ události, check_run.completed, a další přibývají stejným způsobem. Doručení je at-least-once a payload nese event_id kvůli idempotenci. Podpis je HMAC-SHA256 těla v hlavičce X-Candora-Signature. Opakuje se po 1, 5 a 25 minutách, pak se doručení označí jako neúspěšné. Endpoint musí být https a nesmí mířit na privátní adresu.

Sandbox

Klíč cand_test_ nikdy nevolá živý zdroj a chová se pokaždé stejně, takže se na výsledek dá napsat integrační test:

Zaměstnavatel se jménem obsahujícím Fraud skončí v bloku mismatches.
Zaměstnavatel s employerCountry mimo CZ skončí v unverifiable.
Všechno ostatní skončí ve verified_without_finding.

Napište si o sandbox klíč

Verzování

Cesta nese /v1 a změny jsou jen aditivní. Rozbíjející změna znamená /v2 a odpověď reportu nese schema_version, takže uložený report sám říká, v jakém tvaru vznikl.

Plná reference je veřejná

OpenAPI reference se generuje z rout a je veřejně dostupná na app.getcandora.com/api/openapi.json, bez klíče a bez scope. Sandbox klíč tím nezaniká: klíč cand_test_ dál přepíná na fixture adaptéry a chodí na vyžádání.

Chci přístup