Skip to content
thibit docs

Quickstart

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

https://api.uat.thibit.id

1. Get a sandbox API key

Self-serve a sandbox tenant. The key is a test key (tk_test_…) and is returned only once, along with your webhook signing secret.

Terminal window
curl -X POST https://api.uat.thibit.id/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "My app"}'
{
  "tenant_id": "…",
  "api_key": "tk_test_…",
  "webhook_secret": "whsec_…",
  "name": "My app",
  "sandbox": true
}

Send your key as the X-API-Key header on every /v1 call. You can also do all of this in the developer portal without writing code.

2. Create a verification

Decide which documents you accept and create the verification. You get back a hosted onboarding_url to send your user.

Terminal window
curl -X POST https://api.uat.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": "dire" },
      { "country": "*",  "document_type": "passport" }
    ]
  }'
{
  "id": "…",
  "type": "kyc",
  "status": "collecting",
  "onboarding_url": "https://onboard.uat.thibit.id/?token=…"
}

allowed_documents is the allowlist your applicant picks from — a national document for specific countries, plus "*" to accept passports from any issuer. See Accepted documents. (Omit it and the applicant gets the default MZ + passport surface.)

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

4. Get the verdict

Verification runs asynchronously. Receive the result either way:

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

Terminal window
curl -X POST https://api.uat.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.uat.thibit.id/v1/verifications/{id} \
  -H "X-API-Key: tk_test_…"
{
  "id": "…",
  "type": "kyc",
  "status": "completed",
  "country": "MZ",
  "document_type": "bilhete_identidade",
  "decision": "aprovada",
  "confidence": 0.92,
  "result": { "verification_result": { "checks": { } } },
  "documents": ["id_front", "id_back", "selfie"],
  "created_at": "…"
}

status moves collecting → pending → processing → completed | failed. The decision is accept / deny / flag for review (Portuguese verdicts like aprovada may appear from the engine).

Next