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

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

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 — MZ/MX pairs get the fully tuned treatment, while other countries’ passports run with a review-floored outcome. See Accepted documents for the three support tiers.

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

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:

assessmentMeaning
no_material_concernsThe checks surfaced nothing inconsistent.
manual_review_recommendedSomething warrants a human look before you act.
material_inconsistencyThe evidence contains a material inconsistency.
assessment_incompleteThe assessment could not be completed (e.g. an unsupported document, or an engine error).

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

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