Skip to main content

What it’s for

The KYC API runs a full KYC identity check (KYC: know your customer, confirming a customer is who they say they are) from your own onboarding app. You send one call to POST /v1/verify/idp with:
  • the ID document image, front and, for cards, back
  • a liveness capture: short video or camera frames that show a real person was in front of the camera
  • the customer’s ID number, names, date of birth and gender
Sentinel runs the same steps as a check started in the dashboard: document authenticity, liveness, IPRS (Kenya’s national population register), AML screening and face match. See B2 KYC identity checks (in Sentinel’s in-app Help). There is one difference. The API always takes a liveness capture, so a check sent through the API is the only kind that can be approved automatically. Checks from New Verification or a capture link always end in review. The call is asynchronous. It returns an id at once, and the result arrives by webhook or from GET /v1/verify/{id}. Keys, test mode, rate limits and the general error format are in Quick start.

Who can use it

  • Any system holding an API key for your organization with the Run KYC identity checks scope (verify:kyc). To read results by polling, the key also needs Read check results.
  • Admin and Developer create keys and choose their scopes on the API Keys page.
  • Everyone in your organization can see API checks on the Identity (KYC) page. Your team decides checks held for review in Reviews. See B11 Deciding a review case (in Sentinel’s in-app Help).
API Keys page with a key that has the Run KYC identity checks scope

Step by step

The examples read the key from the SENTINEL_API_KEY environment variable, for example gt_test_.... The examples use Sentinel’s production address, https://robust-parakeet-542.convex.site. If API Keys shows a different API address for your organization, use that.

Prepare the media

  1. ID image: a JPEG or PNG of the document. Send the front in documentFrontBase64. For an ID card or driving licence, send the back in documentBackBase64.
  2. Liveness capture: either a video, MP4 (livenessMediaType: "mp4") or WebM ("webm"), or JPEG frames (livenessMediaType: "jpeg_frames"). For frames, join one or more JPEG files byte for byte, then base64-encode the result as one string.
  3. Encode each file as plain base64, without a data: prefix. Each media field can be at most 1,000,000 base64 characters, about 730 KB of file. Resize or compress larger images first.
Use JPEG frames where you can. Face match compares the first JPEG frame with the ID photo. With an MP4 capture, face match doesn’t run.

Send the check

curl

Node (built-in fetch, Node 18+)

Python (requests)

A live key returns 202 with status queued. Keep the id.

Collect the result

  1. Wait for the sentinel.scan.complete webhook with product kyc. Its result holds every step’s output. See Webhooks.
  2. Or poll GET /v1/verify/{id} until status is completed or failed. This returns the verdict but not the step details. See Results and credits.
  3. If the verdict is review, your team decides the case in Reviews. You then get sentinel.review.decided, or a second sentinel.scan.complete with the final verdict.
Webhook delivery log showing a KYC result for Wanjiku Mwangi

What each result means

Request fields

Each media field is at most 1,000,000 base64 characters. The API doesn’t check the format of the text fields. Send the date of birth as YYYY-MM-DD.

Response to the POST (202)

Verdicts

The steps in result

Liveness and the document scan run first. If either needs review, IPRS and AML don’t run and are missing from result. A step that couldn’t reach its provider shows "error": "provider_error", and the check goes to review.

Errors specific to this call

Other errors are in Quick start.

Common questions

How many credits does a KYC check cost?

1 credit on KES plans. On USD plans it is 130 credits on Starter and Trial, 75 on Growth, 63 on Business and 45 on Enterprise. The AML step is included. A pass or reject is charged when it completes, a review when your team decides it, and a failed check isn’t charged.

Can I send a selfie instead of a liveness capture?

No. The API has no selfie field, and the liveness fields are required. A still photo can’t prove the person was present. For a selfie-only flow, use the dashboard or a capture link, which end in review. See B3 Capture links (in Sentinel’s in-app Help).

Does Sentinel keep the images?

No. The images go to the checks and are not stored with the check. Sentinel keeps the names, ID number, date of birth, gender and the step results for your retention period, 7 years by default.

What does a test key return?

status completed, verdict pass and sandbox: true at once, with no providers called and no charge. The request is still validated, so a missing field or an oversized image still fails.

Why is there no reason text for a KYC result?

GET /v1/verify/{id} returns only the verdict for KYC checks. Read the step results in the webhook’s result, or open the report on the Identity (KYC) page.

How long does a check take?

Usually a few minutes. A provider timeout sends the check to review rather than leaving it waiting.