TalentOS API

Two methods. Browser apps use cookie sessions (login sets a 14-day HttpOnly cookie). Programmatic clients use Bearer tokens — generate a key under /account → API keys, then send `Authorization: Bearer tk_…` with every request. Both methods resolve to the same tenant scoping + RBAC; any endpoint marked `session` or `session + role` also accepts a Bearer token of the appropriate role. They are not equivalent beyond that: `resolveCaller()` returns a Bearer caller before the tenant IP allowlist is applied, and the MFA gate exempts API-key callers, so a key is not subject to either control. Keys also carry no expiry — any admin or CHRO can mint an admin-role key that stays valid until someone revokes it by hand.

// Request body
{ "companyName": "Acme Bank", "adminName": "Jane Doe", "adminEmail": "jane@acmebank.com", "password": "••••••••" }

// Response
{ "ok": true, "tenant": { "id": "acme-bank", "name": "Acme Bank" }, "user": { "email": "…", "emailVerified": false, … } }

// Request body
{ "token": "<64-hex>" }

// Response
{ "ok": true, "user": { "emailVerified": true, … } }

// Response
{ "ok": true, "sent": true }

// Request body
{ "email": "jane@acmebank.com", "password": "••••••••" }

// Response
{ "ok": true, "user": { ... } }

// Response
{ "ok": true }

// Response
{ "ok": true, "user": { "email": "...", "name": "...", "role": "...", "tenantId": "..." } }

// Request body
{ "email": "jane@acmebank.com" }

// Response
{ "ok": true, "dryRun": false }

// Request body
{ "token": "<32-byte-hex>", "password": "••••••••" }

// Response
{ "ok": true, "user": { ... } }

// Request body
{ "email": "amara@acmebank.com", "name": "Amara D.", "role": "recruiter" }

// Response
{ "ok": true, "invite": { "inviteUrl": "..." } }

// Request body
{ "token": "<invite-token>", "password": "••••••••" }

// Response
{ "ok": true, "user": { ... } }

Self-tenant operations + team management. Every tenant is isolated; the API never returns cross-tenant data.

// Response
{ "ok": true, "tenant": { "id": "...", "name": "...", "plan": "pilot", "logoUrl": "...", "brandColor": "#7c3aed", "tagline": "..." } }

// Request body
{ "name": "Acme Bank", "tagline": "...", "brandColor": "#7c3aed", "monthlyBudgetUsd": 50 }

// Response
{ "ok": true, "keys": [ { "id": "key_…", "name": "Production sync", "tokenPrefix": "tk_a1b2c3d4", "role": "admin", "createdAt": "…", "createdBy": "jane@acme.com", "lastUsedAt": "…", "revoked": false } ] }

// Request body
{ "name": "Workday integration", "role": "recruiter" }

// Response
{ "ok": true, "key": { "id": "key_…", "tokenPrefix": "tk_a1b2c3d4", … }, "rawToken": "tk_<64-hex>" }

// Response
{ "ok": true }

Job postings. Public read for open status only — used by the careers portal. Admin/recruiter writes only.

// Request body
{ "title": "Senior Backend Engineer", "description": "...", "location": "Lagos", "level": "senior", "employmentType": "full_time", "skills": ["Go", "Postgres"] }

Applicants linked to vacancies. Public apply endpoint for the careers portal; tenant-scoped CRUD for recruiters.

// Request body
{ "vacancyId": "vac_...", "name": "Kwame M.", "email": "kwame@...", "experience": 7, "skills": ["Go"] }

// Response
{ "ok": true, "candidate": { "id": "cand_...", "dedup": false } }

// Request body
{ "stage": "interview" }

// Request body
{ "rows": [ { "name": "...", "email": "...", "vacancyId": "..." } ] }

// Response
{ "ok": true, "total": 100, "created": 87, "updated": 8, "skipped": 5, "errors": [ ... ] }

Formal offer letters extended to candidates at the offer pipeline stage. Accepting an offer auto-bumps the candidate to `hired` and increments the vacancy's hired counter. Status transitions fire `offer.sent`, `offer.accepted`, `offer.declined` webhooks.

// Request body
{ "candidateId": "cand_...", "vacancyId": "vac_...", "baseSalary": 80000, "currency": "USD", "bonus": 10000, "signOnBonus": 5000, "startDate": "2026-06-01", "status": "draft" }

// Response
{ "ok": true, "offer": { "id": "ofr_...", "status": "draft", ... } }

// Request body
{ "status": "accepted", "decision": "Candidate accepted via Slack" }

Scheduled interviews tied to a candidate + vacancy + panel. Scorecards are recorded inline on the interview record. `interview.scheduled` and `interview.completed` webhooks fire on the corresponding transitions.

// Request body
{ "candidateId": "cand_...", "vacancyId": "vac_...", "scheduledAt": "2026-06-01T14:00:00Z", "durationMin": 45, "kind": "video", "locationOrUrl": "https://meet.example.com/x", "interviewers": ["Jane Doe", "John Smith"] }

// Response
{ "ok": true, "interview": { "id": "iv_...", "status": "scheduled", ... } }

// Request body
{ "status": "completed", "addScorecard": { "interviewer": "Jane Doe", "score": 87, "recommendation": "strong_hire", "notes": "Excellent system design." } }

Organisational structure + external partners + connected systems. All three share the same shape — tenant-scoped list/create + per-id get/patch/delete.

Claude-powered features. Each call tracks tokens + cost per tenant and shows up on /spend. Pass entity ids OR inline payloads — server fetches authoritative data when ids are supplied.

// Request body
{ "messages": [...], "stream": true, "language": "en" }

// Request body
{ "candidateId": "cand_...", "vacancyId": "vac_..." }   // OR inline { "candidate": {...}, "job": {...} }

// Response
{ "ok": true, "result": { "matchScore": 87, "verdict": "strong_match", "strengths": [...], "concerns": [...], "recommendation": "..." } }

// Request body
{ "candidateId": "cand_...", "vacancyId": "vac_...", "tone": "warm" }

// Response
{ "ok": true, "result": { "subject": "...", "body": "...", "follow_up_body": "..." } }

// Request body
{ "candidateId": "cand_...", "vacancyId": "vac_...", "baseSalary": 12000, "currency": "USD" }

// Request body
{ "vacancyId": "vac_..." }   // OR { "role": "Backend Engineer", "level": "senior", "skills": [...] }

// Response
{ "ok": true, "result": { "technical": [...], "behavioral": [...], "scenario": [...], "red_flag_signals": [...] } }

// Request body
{ "brief": "Looking for a senior fintech eng with...", "count": 5 }

Saved artifacts from AI calls (JDs, screens, offers, etc.). Tenant-scoped on read and write. Not append-only: the DELETE below hard-deletes the row, there is no soft delete, no version history and no backup to restore from — only the audit event that the deletion happened survives.

// Request body
{ "kind": "jd", "title": "Senior Backend JD", "payload": {...}, "source": "claude" }

File storage. Bytes go to Vercel Blob in production or local FS in dev; metadata in KV. Only the public careers-site purposes are served from the Blob CDN — everything else streams through the authenticated route below. Nothing here is backed up: there is no snapshot, no restore path and no soft delete, so a DELETE is permanent.

Audit trail + executive analytics. Storage is ONE platform-wide Redis list (`talentos:audit:list`): LPUSH on write, then LTRIM to the newest 2,000 events — the cap is shared across all tenants, so another tenant's volume evicts your events and there is no fixed retention period. Rows are not hash-chained, signed or sequence-numbered, so the trail is NOT tamper-evident; GDPR erasure (`redactCandidate`) rewrites rows in place, so it is not immutable either. The list is global, not tenant-scoped — tenant scoping is applied on read: `list()`/`stats()` filter on `tenantId` and return nothing when no scope is passed (deny-by-default), and cross-tenant reads need the platform-admin role plus an explicit `allTenants=1`. For retention beyond the rolling window, export the CSV or stream events to your own SIEM (`/api/tenants/me/siem`).

Data-subject rights endpoints. Admin self-serves export + tenant delete; no support ticket required.

// Request body
{ "confirm": "<tenant-id>" }

Outbound HTTP push. Subscribe an HTTPS endpoint to one or more events; we POST a signed JSON envelope when they happen. Pairs with API keys (pull) to give you a complete integration surface. Every delivery includes an `X-TalentOS-Signature: t=<unix>,v1=<hex>` header where `hex = HMAC-SHA256(t + "." + raw_body, secret)`. Verify the signature on every request — and reject any payload more than 5 minutes old to defeat replay. Available events: `candidate.applied`, `candidate.stage_changed`, `candidate.rejected`, `candidate.merged`, `vacancy.published`, `vacancy.updated`, `vacancy.approval_requested`, `vacancy.approved`, `offer.approval_requested`, `offer.approved`, `offer.rejected`, `offer.sent`, `offer.viewed`, `offer.signed`, `offer.accepted`, `offer.declined`, `offer.expired`, `interview.scheduled`, `interview.rescheduled`, `interview.cancelled`, `interview.completed`, `interview.feedback_submitted`, `approval.requested`, `approval.decided` (the live list is always in the `availableEvents` field of GET /api/tenants/me/webhooks). Delivery is durable: failed deliveries enter a retry queue with exponential backoff (30s → 2m → 10m → 1h → 6h) and the subscription auto-disables after 20 consecutive failures.

// Response
{ "ok": true, "webhooks": [ { "id": "wh_…", "url": "https://…", "events": ["candidate.applied"], "enabled": true, "createdAt": "…", "lastDeliveryAt": "…", "lastStatus": "200" } ], "availableEvents": ["candidate.applied", "candidate.stage_changed", "vacancy.published"] }

// Request body
{ "url": "https://your-system.example.com/talentos-hook", "events": ["candidate.applied", "vacancy.published"] }

// Response
{ "ok": true, "webhook": { "id": "wh_…", "url": "…", "events": [...], "secret": "whsec_<64-hex>", "enabled": true, … } }

// Response
{ "ok": true }

The tenant's connected tools — Slack / Teams channels, calendar accounts, job-board feeds, HRIS export. The catalogue is honest: a provider only ever shows as connected when a real, working row exists for your workspace; env-gated providers (calendar OAuth) report `needs_env` until the deployment operator adds the client credentials.

// Response
{ "ok": true, "providers": [ { "id": "slack", "name": "Slack", "category": "communication", "availability": "live", "connected": true, "rows": [...] } ], "email": { "active": false, "note": "dry-run" } }

// Request body
{ "provider": "slack", "displayName": "#hiring", "config": { "webhookUrl": "https://hooks.slack.com/services/…", "events": ["candidate.applied", "offer.accepted"] } }

// Response
{ "ok": true, "delivered": true, "status": 200 }

// Request body
{ "vacancyId": "vac_…", "channel": "linkedin-feed", "url": "https://…", "action": "mark" }

Google Calendar / Microsoft 365 sync for interviews, plus a standards-based .ics fallback that always works. OAuth connect is env-gated — when the deployment has no OAuth client configured the UI says so truthfully and interviews still carry .ics invites by email.

// Request body
{ "emails": ["jane@acme.com"], "from": "2026-09-01T08:00:00Z", "to": "2026-09-01T18:00:00Z" }

// Response
{ "ok": true, "provider": "google", "busy": { "jane@acme.com": [{ "start": "…", "end": "…" }] }, "errors": {} }

// Request body
{ "interviewId": "iv_…" }

Public per-tenant feeds job boards crawl, plus schema.org JobPosting JSON-LD embedded on every public vacancy page for Google for Jobs. Feeds list only open, non-internal vacancies, refresh hourly, and never include recruiter emails. Tenants opt out with feature flags (indeedFeed / linkedinFeed).

The candidate side of native offer e-signature. The 256-bit token in the signing link is the credential (same posture as a password-reset link) — no account needed. Requests are rate-limited per IP — 30/min on the GET, 10/min on the POST — by the same in-process counter used elsewhere, so the cap is per function instance rather than fleet-wide; accepting stores a full evidence record (typed name, IP, user agent, SHA-256 of the letter body) and fires offer.viewed / offer.signed / offer.accepted webhooks.

// Request body
{ "action": "accept", "signedName": "Jane Doe", "agree": true }  |  { "action": "decline", "reason": "…" }

// Response
{ "ok": true, "url": "https://…/offer/<token>", "dryRun": false }

Operational endpoints. Public; safe to expose to monitors + uptime tools.