Dokumentace API

• Základní adresa: https://hireup.inflexion.cz/api/v1, JSON přes HTTPS. Strojově čitelná specifikace: OpenAPI 3.1.
• Autentizace hlavičkou x-api-key. Klíč vydává vlastník firmy v HR portálu (Integrace) a patří firmě, ne osobě. Každý klíč vidí jen data své firmy.
• Limit: 10 000 požadavků za 24 hodin na klíč (pak 429). Na výsledky nečekejte dotazováním – použijte webhook.
• Chyby vrací JSON { "error": "kód" } se stavem 400/401/404/409.

curl https://hireup.inflexion.cz/api/v1/positions \
  -H "x-api-key: hu_…"

Webhook vašeho ATS zavolá POST /intake hned, jak uchazeč přijde z inzerátu. Pošlete pozici, uchazeče a CV (cvText nebo PDF v cvPdfBase64, do 5 MB). Vše ostatní uděláme my: profil z CV, screening a pozvánku e-mailem ("sendInvite": false ji vypne).

POST https://hireup.inflexion.cz/api/v1/intake
{ "positionId": "…",
  "candidate": { "fullName": "Eva Nováková", "email": "eva@example.com", "externalRef": "ID v ATS" },
  "cvPdfBase64": "JVBERi0x…" }

202 { "candidateId": "…", "status": "waiting_for_profile", "existingCandidate": false }
    // nebo "screening_created" + screeningId (+ inviteUrl při novém založení)

• Profil z CV trvá obvykle do 30 s. Do té doby je stav waiting_for_profile; screening založíme, jakmile bude hotový, a dáme vám vědět webhookem screening.created.
• Opakované volání se stejným externalRef nezaloží duplicitu – vrátí existujícího uchazeče (a jeho živý screening). inviteUrl se vrací jen při novém založení.
• Limit těla požadavku hostingu je řádově jednotky MB; větší PDF pošlete jako cvText.

1. GET /positions – aktivní pozice se schválenou rubrikou.
2. POST /candidates – uchazeč s textem CV; profil je hotový obvykle do 30 s (profileReady).
3. POST /screenings – screening a odkaz pro uchazeče (inviteUrl, jen v této odpovědi). S "sendInvite": true pošleme pozvánku e-mailem my.
4. Po dokončení přijde webhook screening.completed s doporučením a odkazem na report. Rozhoduje personalista v HireUP.

Adresu webhooku (https) přidá správce v HR portálu → Integrace. Odebíráme dvě události: screening.created (screening založený přes /intake; v data jen screeningId, candidate a position s ID, status a inviteSent) a screening.completed. Webhook adresy přidané před zavedením screening.created odebírají jen dokončení – přidejte adresu znovu. Po dokončení hodnocení pošleme POST s tělem:

{
  "id": "…",                      // ID doručení (pro deduplikaci)
  "type": "screening.completed",
  "createdAt": "2026-09-26T10:00:00.000Z",
  "data": {
    "screeningId": "…",
    "candidate": { "id": "…", "externalRef": "ID ve vašem ATS" },
    "position": { "id": "…", "title": "…" },
    "recommendation": "advance" | "consider" | "reject",
    "summary": "…",
    "competencies": [{ "key": "…", "name": "…", "score": 1–5 | null, "confidence": "…" }],
    "reportUrl": "https://hireup.inflexion.cz/dashboard/screenings/…",
    "decisionRequired": true
  }
}

Každá zpráva má hlavičku HireUP-Signature: t=<unix>,v1=<hex>, kde v1 = HMAC-SHA256(tajemství, "t.tělo"). Ověřte podpis a odmítněte zprávy starší než 5 minut. Neúspěšné doručení (jiný stav než 2xx, timeout 10 s) opakujeme až 5×.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyHireup(secret, rawBody, header, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

• Na žádost uchazeče o výmaz zavolejte DELETE /candidates/{id} – smaže CV, screeningy, záznamy i hodnocení.
• Jinak se data smažou automaticky po lhůtě uchování nastavené firmou.
• Webhook nenese přepis ani citace – ty zůstávají v reportu v HireUP.