Quickstart

Run one check and receive its result, end to end.

One check, from the request to the webhook that carries the answer. About ten minutes, all in sandbox, nothing billable.

Create a test key

In your Verifisha workspace, create a vrf_test_ key. Test keys run against staging — no check they run is billable.

Every call below sends it the same way, with the word Bearer and a space in front of the key:

Authorization: Bearer vrf_test_9f2cA7...

Bearer is part of the header, not part of your key. If a call comes back 401, the header is usually why.

Keep the key server-side. Anyone holding it can act as your workspace.

Point a webhook at yourself

Results arrive by webhook, so you need somewhere to receive one. For a first run, anything with a public URL will do — a tunnel to your laptop, or a throwaway inbox like webhook.site.

curl -X POST https://api.verifisha.com/api/v1/webhooks/config \
  -H "Authorization: Bearer vrf_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-endpoint.example.com/hooks/verifisha",
    "enabledEvents": ["report.ready", "report.failed"],
    "secret": "a-long-random-string"
  }'

Your handler needs to do one thing today: answer 200 quickly.

app.post("/hooks/verifisha", (req, res) => {
  res.sendStatus(200);          // acknowledge first
  console.log(req.body);        // then look at what arrived
});

Run one check

The smallest request that does something: one subject, one check.

curl -X POST https://api.verifisha.com/api/v1/reports \
  -H "Authorization: Bearer vrf_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reports": [{
      "subject": {
        "subjectType": "INDIVIDUAL",
        "fullName": "Jane Doe",
        "idNumber": "36901234"
      },
      "checksRequested": ["IDENTITY"],
      "purpose": "Employment screening",
      "consent": { "mode": "CUSTOMER_ATTESTED", "obtained": true }
    }]
  }'

You get back the report's id and its status — not the result. The checks are still running.

{
  "count": 1,
  "reports": [{ "id": "rpt_123", "status": "PROCESSING" }]
}

CUSTOMER_ATTESTED says you already have the subject's consent, so nothing waits on them and the check runs immediately. Use { "mode": "VERIFISHA_HOSTED" } instead and Verifisha emails the subject for consent first — useful, but then your quickstart waits on a human. See consent.

Receive the result

When the check finishes, report.ready arrives at your endpoint:

{
  "lifecycle": { "event": "report.ready", "terminal": true },
  "report": {
    "id": "rpt_123",
    "status": "COMPLETED",
    "riskLevel": "LOW"
  },
  "checks": [{
    "name": "IDENTITY",
    "status": "COMPLETED",
    "riskLevel": "LOW",
    "flags": []
  }]
}

Three fields decide what you do next:

  • lifecycle.terminal — true means nothing more is coming. Act now.
  • check.status — COMPLETED means it ran. It does not mean the subject passed.
  • check.riskLevel and flags — what it actually found. Your policy decides what that means.

A check that finds a sanctions match is also COMPLETED. Branch on riskLevel and flags, never on status alone — see statuses and outcomes.

That is the whole loop: request, wait, act on the delivery.

Go live

When it works in sandbox, request go-live from your workspace.

  • Signed up as an individual? Your account becomes a business workspace.
  • Upload your business KYB documents.
  • Verifisha runs a business verification check on your company.

You will then receive an email containing your vrf_live_ API key. Swap it in — the host does not change. Treat that email as a secret.

Next

Build with an AI assistant

Paste this into Claude, Cursor, Copilot or ChatGPT to have it write the integration against the current contract rather than from memory.

You are helping me integrate the Verifisha API (identity, tax, credit,
employment and business verification for Kenya).

Read these first and follow them over anything you already believe about this API:
https://docs.verifisha.com/llms.txt
https://docs.verifisha.com/quickstart
https://docs.verifisha.com/guides/webhooks

What matters:
- Base URL is https://api.verifisha.com and every path starts with /api/v1.
- Authenticate with "Authorization: Bearer <key>" or "X-API-Key: <key>".
  A vrf_test_ key is routed to staging; a vrf_live_ key can run billable
  checks. The host is the same for both.
- POST /api/v1/reports takes a "reports" array (up to 500) and runs the checks
  named in each entry. Send an Idempotency-Key header so a retry cannot create
  a second billable report.
- Consent: if my own flow already has the subject's agreement, send
  consent.mode CUSTOMER_ATTESTED with the evidence fields. Otherwise send
  VERIFISHA_HOSTED and Verifisha asks them.
- Results arrive by webhook — report.ready and report.failed for the whole
  report, check.started / check.completed / check.failed for progress, and
  monitoring.alert.created for alerts. Do not poll.
- check.status COMPLETED means the check ran, not that the subject passed.
  Branch on riskLevel and flags. FAILED is an execution failure, never an
  adverse finding.
- Verify X-Verifisha-Signature against the raw body, and check
  X-Verifisha-Environment before acting on a delivery.
- List endpoints are paged: items, page, size, totalItems, totalPages,
  hasNext, hasPrevious. Loop on hasNext.
- Errors are RFC 7807 problem+json. Branch on errorCode, never on wording.

My stack is <language and framework>. I want to <what you are building>.
Write the integration, and tell me where you were unsure rather than guessing.

Every page is in llms.txt, so an assistant can pull the current docs instead of recalling an older version of this API.

On this page