Skip to content
thibit docs

Quickstart

This walks you from zero to a completed verification. Base URL for everything below:

https://api.thibit.id

1. Get a project API key

Section titled “1. Get a project API key”

Sign in to the dashboard with Google or GitHub. On first login you get an org with a default Sandbox project and a test key (tk_test_…). Create, view, and revoke project-scoped keys under Integrate → Keys (a key’s value is shown once). Set your key as the X-API-Key header on every /v1 call.

2. Create a verification

Section titled “2. Create a verification”

Decide which documents you accept and create the verification. You get back a hosted onboarding_url to send your user. Country codes are always explicit ISO-3166-1 alpha-2 — wildcards are rejected.

Mozambique — accept the Bilhete de Identidade or an MZ-issued passport:

Terminal window
curl -X POST https://api.thibit.id/v1/verifications \
  -H "X-API-Key: tk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "kyc",
    "allowed_documents": [
      { "country": "MZ", "document_type": "bilhete_identidade" },
      { "country": "MZ", "document_type": "passport" }
    ]
  }'

Mexico — accept the national ID (INE) or an MX-issued passport:

Terminal window
curl -X POST https://api.thibit.id/v1/verifications \
  -H "X-API-Key: tk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "kyc",
    "allowed_documents": [
      { "country": "MX", "document_type": "national_id" },
      { "country": "MX", "document_type": "passport" }
    ]
  }'
{
  "id": "…",
  "type": "kyc",
  "status": "collecting",
  "onboarding_url": "https://onboard.thibit.id/?token=…",
  "short_url": "https://thibit.id/s/…"
}

allowed_documents is the allowlist your applicant picks from. Any explicit country’s passport can be listed — the MZ and MX documents above are assessed, while other countries’ passports are accepted for manual review, not assessed. See Accepted documents for what each document gets.

Section titled “3. Send the link”

Open onboarding_url yourself to try it, or send your user the short_url. They pick a document from your allowlist, photograph it, take a selfie, and submit — all on their phone, no account.

4. Get the assessment

Section titled “4. Get the assessment”

Verification runs asynchronously. Receive the result either way:

Webhook (recommended) — set a URL once and thibit POSTs the signed result when it finishes. See Webhooks.

Terminal window
curl -X POST https://api.thibit.id/v1/webhook \
  -H "X-API-Key: tk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-app.com/webhooks/thibit"}'

Polling — fetch the verification by id until status is terminal:

Terminal window
curl https://api.thibit.id/v1/verifications/{id} \
  -H "X-API-Key: tk_test_…"
{
  "id": "…",
  "type": "kyc",
  "status": "completed",
  "country": "MZ",
  "document_type": "bilhete_identidade",
  "assessment": "no_material_concerns",
  "advisory": true,
  "confidence": 0.92,
  "result": { "verification_result": { "checks": { } } },
  "documents": ["id_front", "id_back", "selfie"],
  "created_at": "…"
}

status moves collecting → pending → processing → completed | failed. The assessment is one of exactly four values:

assessment Meaning
no_material_concerns The checks surfaced nothing inconsistent.
manual_review_recommended Something warrants a human look before you act.
material_inconsistency The evidence contains a material inconsistency.
assessment_incomplete The assessment could not be completed (e.g. an unsupported document, an engine error, or a link that expired before the applicant submitted — which sends no webhook).

Every assessment is advisory — thibit reports identity signals; the final business decision is always yours. If your team records its own outcome on a Case, that is stored as a separate customer_disposition and never changes the assessment. See Verification flow.

Beyond the direct create

Section titled “Beyond the direct create”

POST /v1/verifications is the fastest path and stays fully supported. When you want a reusable, shareable flow — a stable hosted link, capture pre-filled from data you already hold, and a check that matches the person against your records — author a Flow in the dashboard and run it with POST /v1/flows/{slug}/intake. See Templates, Flows & Cases.

Next

Section titled “Next”