API overview

The integrator API is /v1. The full schema is on the Reference page (generated from the committed OpenAPI spec, release 1.0.0).

Base URL

Environment	Base URL
Production	https://api.thibit.id

Authentication

Every machine /v1 call is scoped by a project API key in the X-API-Key header:

X-API-Key: tk_test_…

Get a project API key from the dashboard: sign in with Google or GitHub, and create/list/revoke project-scoped keys inside an org → project. Keys are project-scoped; keep them server-side. The OAuth/session plane (the /auth/* routes the dashboard uses to sign you in) is internal to the dashboard and not part of the machine-to-machine /v1 contract documented here.

Endpoints

There are two ways to start a verification:

• Create directly — POST /v1/verifications mints a verification from an inline allowed-documents list. No Template to author; fully back-compatible.
• Run a Flow — POST /v1/flows/{slug}/intake runs a Flow you activated in the dashboard, pre-filling capture from your payload and stamping your reference record. See Templates, Flows & Cases.

Verifications (machine, X-API-Key)

Method	Path	Purpose
POST	/v1/signup	Self-serve sandbox tenant + key. Local/dev only — disabled in production (403); use the dashboard to get a project key.
GET	/v1/me	For api-key callers: your tenant profile (name, webhook URL, sandbox flag).
POST	/v1/keys/rotate	Rotate your API key (the old key is invalidated).
POST	/v1/verifications	Create a verification → { id, onboarding_url, short_url }.
GET	/v1/verifications	List your recent verifications (the log).
GET	/v1/verifications/{id}	Fetch one verification’s status + assessment.
DELETE	/v1/verifications/{id}	Erase a verification’s PII (GDPR-style) → a PII-safe receipt; the record’s status becomes erased.
POST	/v1/verifications/{id}/ubos	Declare beneficial owners — KYB, not in this release (production rejects type: "kyb").
POST	/v1/flows/{slug}/intake	Run a Flow for a payload → mints a Case + link (project-scoped key).
POST	/v1/webhook	Set/clear the legacy tenant-level webhook URL (project webhooks below are preferred).

Project management (dashboard session or project scope)

These routes back the dashboard’s Integrate, Team, and Settings surfaces. They are driven by a signed-in dashboard session (Google/GitHub OAuth) and gated per-permission; non-members get a 404.

Method	Path	Purpose
GET	/v1/projects/{id}/keys	List a project’s API keys.
POST	/v1/projects/{id}/keys	Create a project API key (raw value shown once).
DELETE	/v1/projects/{id}/keys/{key_id}	Revoke a project key (idempotent).
GET	/v1/projects/{id}/webhook	Read the project webhook config (never returns the secret).
PUT	/v1/projects/{id}/webhook	Set the project webhook URL; mints the signing secret on first set (returned once).
DELETE	/v1/projects/{id}/webhook	Clear the webhook URL (the secret is retained for re-enabling).
GET	/v1/projects/{id}/branding	Read the project’s hosted-page branding.
PUT	/v1/projects/{id}/branding	Set the project’s hosted-page branding.
GET	/v1/team/members	The active org’s members (email + name + role).
GET	/v1/team/invitations	Pending invitations for the active org.
POST	/v1/team/invitations	Invite a colleague by email + role — they auto-join on their next OAuth sign-in (no email is sent yet).
DELETE	/v1/team/invitations/{id}	Revoke a pending invitation.
GET	/v1/primitives	The public registry of composable verification pieces behind the Build composer.

The dashboard’s Build / Flows / Verifications / Case Management surfaces are driven by session-scoped dashboard routes that are not part of the machine contract — use the dashboard for those.

Note

GET /v1/me is dual-plane. With an X-API-Key it returns the api-key tenant profile shown above. With a dashboard session cookie it instead boots the signed-in user (your orgs, projects, the active project, and your effective permissions).

Intake — run a Flow

Once you’ve activated a Flow in the dashboard (Build → Flows), run it by POSTing the data you already hold. Use a project-scoped API key.

curl -X POST https://api.thibit.id/v1/flows/{slug}/intake \
  -H "X-API-Key: tk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "full_name": "Ana Sitoe",
      "dob": "1994-03-12",
      "id_number": "110100..."
    },
    "verifiee": { "email": "ana@example.com" }
  }'

{
  "id": "…",
  "flow_id": "…",
  "flow_slug": "swift-harbor-x7k2m9",
  "flow_version_ref": 3,
  "status": "collecting",
  "onboarding_url": "https://onboard.thibit.id/?token=…",
  "short_url": "https://thibit.id/s/…",
  "link": "https://thibit.id/s/…"
}

payload is validated against the Flow’s declared intake shape (a missing required field is a 400 naming the key). Mapped fields pre-fill capture for the verifiee; the whole payload (or an explicit claimed object) is stored on the Case as your reference record for record match. link is the short apex link to send the verifiee. The Case is read back from the dashboard’s Verifications surface.

Verification lifecycle

collecting → pending → processing → completed | failed — plus erased after a DELETE /v1/verifications/{id}. Creation returns immediately; the engine runs asynchronously and the result arrives by webhook or polling GET /v1/verifications/{id}. Terminal results carry an advisory assessment (no_material_concerns | manual_review_recommended | material_inconsistency | assessment_incomplete) — see Verification flow.

Conventions

• Async, not blocking — never hold a request open waiting for a result.
• Idempotency — store your own applicant-to-verification mapping; don’t blind-retry POST /v1/verifications.
• Errors — standard HTTP status codes; 401 = missing/invalid X-API-Key.