Links

Create a link

Creates a link the person opens on their phone. An ID number link asks for their NIN or BVN with name and date of birth. A face link adds a face check against their ID photo. You get verification.completed when they finish. The url is returned once.

POST/v1/kyc/links

Request

Authenticate with Authorization: Bearer <your key>. Send a JSON body.

Body

purposestringrequired
ID number links: a KYC purpose code (as on checks). Face links: hiring, rider_onboarding, guest_check_in, tenant, customer_onboarding or other.
stepsarray of "id_number" | "face" | "document" | "bvn" | "address"
["id_number"] alone, or "face" with any of "document" (allow an ID document instead of the NIN), "bvn" (also check the BVN; not with document) and "address" (ask for and tag their address). Face steps need the matching capability on your account. Default ["id_number"].
check_type"nin_basic" | "nin_premium" | "bvn_validate"
ID number links only (required there).
customer_refstring
Your ID for the person. Links checks to one customer record.
namestring
ID number links: first name, to greet them (optional, up to 80). Face links: full name as on their ID (required). Up to 120 characters.
phonestring
Face links only, optional.
emailstring (email)
Face links only, optional.
redirect_urlstring (uri)
https:// only. Shown as a "Back to" button once they finish (both kinds of link). Up to 500 characters.

Example

POST /v1/kyc/links

curl -X POST https://api.verath.io/v1/kyc/links \
  -H "Authorization: Bearer $VERATH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"steps":["id_number"],"check_type":"nin_basic","purpose":"KYC-ONB","customer_ref":"cust_1042","name":"Ngozi"}'

201 Created

{
  "id": "lnk_5b0c2e7d9a1f4e3c8b6a2d1e0f9c8b7a",
  "object": "link",
  "kind": "match",
  "steps": [
    "id_number"
  ],
  "mode": "test",
  "check": "nin_basic",
  "purpose": "KYC-ONB",
  "customer_ref": "cust_1042",
  "name": "Ngozi",
  "status": "pending",
  "attempts": 0,
  "opened_at": null,
  "completed_at": null,
  "expires_at": "2026-11-18T15:32:00.000Z",
  "created_at": "2026-11-11T15:32:00.000Z",
  "result": null,
  "url": "https://verath.io/kl/…"
}

Responses

Status	Meaning
201	Created.
400	Invalid request.
401	Missing, invalid or revoked API key.
403	capability_not_enabled, kyc_unavailable or pricing_not_set.
429	Rate limited. Honour Retry-After.