{"openapi":"3.1.0","info":{"title":"Verath KYC API","version":"1.0.0","description":"Outage-proof NIN and BVN checks. Match-first: per-field match scores by default; record fields only for approved businesses and sources whose contract allows it. Sources are named by label only."},"servers":[{"url":"https://api.verath.io"}],"paths":{"/v1/kyc/nin/basic":{"post":{"summary":"NIN basic: name, date of birth, gender","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"},"description":"Repeats within 24 hours return the stored result, free."},{"name":"X-Simulate-Outage","in":"header","required":false,"schema":{"type":"string","enum":["registry","all"]},"description":"Test keys only: simulate a source outage."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nin","purpose"],"properties":{"nin":{"type":"string","pattern":"^\\d{11}$"},"first_name":{"type":"string","maxLength":100},"middle_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"dob":{"type":"string","format":"date","description":"YYYY-MM-DD"},"phone":{"type":"string","maxLength":100},"gender":{"type":"string","enum":["male","female"]},"purpose":{"type":"string","enum":["KYC-ONB","KYC-REV","LEND","EMPL"],"description":"Why you are checking (recorded on every check)."},"consent_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your reference for the person's consent."},"customer_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your ID for the person. Links checks to one customer record."}}}}}},"responses":{"200":{"description":"Completed: found or not found.","headers":{"Request-Id":{"schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds or budget_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"capability_not_enabled, kyc_unavailable or pricing_not_set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict or idempotency_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"identity_locked: the owner locked this NIN or BVN on Verath (businesses that honour locks). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"upstream_unavailable: no source answered. The check is pending and retried for up to 72 hours (verification.completed / verification.failed). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"429":{"description":"Rate limited. Honour Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/kyc/nin/premium":{"post":{"summary":"NIN premium: adds photo, origin and residence (records only when approved)","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"},"description":"Repeats within 24 hours return the stored result, free."},{"name":"X-Simulate-Outage","in":"header","required":false,"schema":{"type":"string","enum":["registry","all"]},"description":"Test keys only: simulate a source outage."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nin","purpose"],"properties":{"nin":{"type":"string","pattern":"^\\d{11}$"},"first_name":{"type":"string","maxLength":100},"middle_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"dob":{"type":"string","format":"date","description":"YYYY-MM-DD"},"phone":{"type":"string","maxLength":100},"gender":{"type":"string","enum":["male","female"]},"purpose":{"type":"string","enum":["KYC-ONB","KYC-REV","LEND","EMPL"],"description":"Why you are checking (recorded on every check)."},"consent_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your reference for the person's consent."},"customer_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your ID for the person. Links checks to one customer record."}}}}}},"responses":{"200":{"description":"Completed: found or not found.","headers":{"Request-Id":{"schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds or budget_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"capability_not_enabled, kyc_unavailable or pricing_not_set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict or idempotency_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"identity_locked: the owner locked this NIN or BVN on Verath (businesses that honour locks). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"upstream_unavailable: no source answered. The check is pending and retried for up to 72 hours (verification.completed / verification.failed). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"429":{"description":"Rate limited. Honour Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/kyc/vnin":{"post":{"summary":"Virtual NIN token","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"},"description":"Repeats within 24 hours return the stored result, free."},{"name":"X-Simulate-Outage","in":"header","required":false,"schema":{"type":"string","enum":["registry","all"]},"description":"Test keys only: simulate a source outage."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vnin","purpose"],"properties":{"vnin":{"type":"string","pattern":"^[A-Za-z0-9]{16}$"},"first_name":{"type":"string","maxLength":100},"middle_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"dob":{"type":"string","format":"date","description":"YYYY-MM-DD"},"phone":{"type":"string","maxLength":100},"gender":{"type":"string","enum":["male","female"]},"purpose":{"type":"string","enum":["KYC-ONB","KYC-REV","LEND","EMPL"],"description":"Why you are checking (recorded on every check)."},"consent_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your reference for the person's consent."},"customer_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your ID for the person. Links checks to one customer record."}}}}}},"responses":{"200":{"description":"Completed: found or not found.","headers":{"Request-Id":{"schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds or budget_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"capability_not_enabled, kyc_unavailable or pricing_not_set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict or idempotency_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"identity_locked: the owner locked this NIN or BVN on Verath (businesses that honour locks). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"upstream_unavailable: no source answered. The check is pending and retried for up to 72 hours (verification.completed / verification.failed). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"429":{"description":"Rate limited. Honour Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/kyc/bvn/validate":{"post":{"summary":"BVN validate: per-field match scores","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"},"description":"Repeats within 24 hours return the stored result, free."},{"name":"X-Simulate-Outage","in":"header","required":false,"schema":{"type":"string","enum":["registry","all"]},"description":"Test keys only: simulate a source outage."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bvn","purpose"],"properties":{"bvn":{"type":"string","pattern":"^\\d{11}$"},"first_name":{"type":"string","maxLength":100},"middle_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"dob":{"type":"string","format":"date","description":"YYYY-MM-DD"},"phone":{"type":"string","maxLength":100},"gender":{"type":"string","enum":["male","female"]},"purpose":{"type":"string","enum":["KYC-ONB","KYC-REV","LEND","EMPL"],"description":"Why you are checking (recorded on every check)."},"consent_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your reference for the person's consent."},"customer_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your ID for the person. Links checks to one customer record."}}}}}},"responses":{"200":{"description":"Completed: found or not found.","headers":{"Request-Id":{"schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds or budget_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"capability_not_enabled, kyc_unavailable or pricing_not_set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict or idempotency_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"identity_locked: the owner locked this NIN or BVN on Verath (businesses that honour locks). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"upstream_unavailable: no source answered. The check is pending and retried for up to 72 hours (verification.completed / verification.failed). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"429":{"description":"Rate limited. Honour Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/kyc/nin/selfie":{"post":{"summary":"NIN + selfie: passive liveness, then a face match against the NIN photo. match.face and match.liveness are 0–100. Sandbox selfie_image tokens: test_match, test_other_person, test_spoof.","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"},"description":"Repeats within 24 hours return the stored result, free."},{"name":"X-Simulate-Outage","in":"header","required":false,"schema":{"type":"string","enum":["registry","all"]},"description":"Test keys only: simulate a source outage."}],"responses":{"200":{"description":"Completed: found or not found.","headers":{"Request-Id":{"schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds or budget_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"capability_not_enabled, kyc_unavailable or pricing_not_set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict or idempotency_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"identity_locked: the owner locked this NIN or BVN on Verath (businesses that honour locks). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"upstream_unavailable: no source answered. The check is pending and retried for up to 72 hours (verification.completed / verification.failed). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"429":{"description":"Rate limited. Honour Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nin","selfie_image","purpose"],"properties":{"nin":{"type":"string","pattern":"^\\d{11}$"},"selfie_image":{"type":"string","description":"Base64 JPEG or PNG (optionally a data: URI), up to 1 MB. Not kept after the check."},"first_name":{"type":"string","maxLength":100},"middle_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"dob":{"type":"string","format":"date","description":"YYYY-MM-DD"},"phone":{"type":"string","maxLength":100},"gender":{"type":"string","enum":["male","female"]},"purpose":{"type":"string","enum":["KYC-ONB","KYC-REV","LEND","EMPL"],"description":"Why you are checking (recorded on every check)."},"consent_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your reference for the person's consent."},"customer_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your ID for the person. Links checks to one customer record."}}}}}}}},"/v1/kyc/aml/screen":{"post":{"summary":"AML screen: sanctions and PEP lists. found: true means possible matches, listed in screening.hits for a person to review. Sandbox: last name Sanctioned or Politico.","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$"},"description":"Repeats within 24 hours return the stored result, free."},{"name":"X-Simulate-Outage","in":"header","required":false,"schema":{"type":"string","enum":["registry","all"]},"description":"Test keys only: simulate a source outage."}],"responses":{"200":{"description":"Completed: found or not found.","headers":{"Request-Id":{"schema":{"type":"string"}},"Idempotent-Replayed":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_funds or budget_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"capability_not_enabled, kyc_unavailable or pricing_not_set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict or idempotency_in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"423":{"description":"identity_locked: the owner locked this NIN or BVN on Verath (businesses that honour locks). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"424":{"description":"upstream_unavailable: no source answered. The check is pending and retried for up to 72 hours (verification.completed / verification.failed). Never billed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"429":{"description":"Rate limited. Honour Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["first_name","last_name","purpose"],"properties":{"first_name":{"type":"string","maxLength":100},"middle_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"dob":{"type":"string","format":"date","description":"YYYY-MM-DD"},"purpose":{"type":"string","enum":["KYC-ONB","KYC-REV","LEND","EMPL"],"description":"Why you are checking (recorded on every check)."},"consent_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your reference for the person's consent."},"customer_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your ID for the person. Links checks to one customer record."}}}}}}}},"/v1/kyc/links":{"post":{"summary":"Create a link for a person to complete on their phone. steps [\"id_number\"] (the default): they enter their NIN or BVN with name and date of birth (needs check_type). steps [\"face\", …]: they enter their NIN or show an ID document, then a face check against the photo (needs name; Verify purposes). You get verification.completed with link_id and link_kind. The url is shown once.","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purpose"],"properties":{"steps":{"type":"array","items":{"type":"string","enum":["id_number","face","document","bvn","address"]},"default":["id_number"],"description":"[\"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."},"check_type":{"type":"string","enum":["nin_basic","nin_premium","bvn_validate"],"description":"ID number links only (required there)."},"purpose":{"type":"string","description":"ID number links: a KYC purpose code (as on checks). Face links: hiring, rider_onboarding, guest_check_in, tenant, customer_onboarding or other."},"customer_ref":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$","description":"Your ID for the person. Links checks to one customer record."},"name":{"type":"string","maxLength":120,"description":"ID number links: first name, to greet them (optional, up to 80). Face links: full name as on their ID (required)."},"phone":{"type":"string","description":"Face links only, optional."},"email":{"type":"string","format":"email","description":"Face links only, optional."},"redirect_url":{"type":"string","format":"uri","maxLength":500,"description":"https:// only. Shown as a \"Back to\" button once they finish (both kinds of link)."}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Link"},{"type":"object","properties":{"url":{"type":"string"}}}]}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"capability_not_enabled, kyc_unavailable or pricing_not_set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Honour Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/kyc/links/{id}":{"get":{"summary":"Fetch a link, with its check once finished","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^(lnk|vlk)_[0-9a-f]{32}$"},"description":"lnk_ for ID number links, vlk_ for face links."}],"responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Link"}}}},"404":{"description":"No such link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallet":{"get":{"summary":"Your wallet: balance, money held for running checks, available, alert level and this month's spend","security":[{"apiKey":[]}],"responses":{"200":{"description":"The wallet (live money; the same whichever key asks).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}}}}},"/v1/kyc/checks/{reference_id}":{"get":{"summary":"Fetch a check (for example, one that was pending)","security":[{"apiKey":[]}],"parameters":[{"name":"reference_id","in":"path","required":true,"schema":{"type":"string","pattern":"^chk_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"The check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"404":{"description":"No such check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"verification.completed":{"post":{"summary":"A pending check completed, or a link finished (with link_id and link_kind: match or face)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledge with any 2xx."}}}},"wallet.low_balance":{"post":{"summary":"The available balance dropped below your alert level (at most once a day). data is the wallet.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledge with any 2xx."}}}},"verification.failed":{"post":{"summary":"A pending check gave up after 72 hours (never billed)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledge with any 2xx."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"vk_test_… (sandbox) or vk_live_…"}},"schemas":{"Wallet":{"type":"object","properties":{"object":{"type":"string","enum":["wallet"]},"currency":{"type":"string","enum":["NGN"]},"balance_kobo":{"type":"integer"},"held_kobo":{"type":"integer","description":"Held for checks still running"},"available_kobo":{"type":"integer","description":"balance_kobo − held_kobo: what new checks can use"},"low_balance_kobo":{"type":["integer","null"],"description":"Your alert level (Billing), or null"},"below_low_balance":{"type":"boolean"},"monthly_cap_kobo":{"type":["integer","null"]},"month_spend_kobo":{"type":"integer","description":"Charged since the 1st (Lagos time)"},"updated_at":{"type":"string","format":"date-time"}}},"RouteStep":{"type":"object","properties":{"source":{"type":"string"},"outcome":{"type":"string","enum":["found","not_found","error","timeout","malformed","skipped"]},"latency_ms":{"type":"integer"},"ref":{"type":"string","description":"The source's own reference for this call, when it gives one."}}},"Check":{"type":"object","properties":{"reference_id":{"type":"string"},"object":{"const":"check"},"check":{"type":"string","enum":["nin_basic","nin_premium","vnin","bvn_validate","nin_selfie","aml_screen"]},"status":{"type":"string","enum":["processing","completed","pending","failed"]},"found":{"type":["boolean","null"]},"source":{"type":["string","null"]},"source_ref":{"type":["string","null"],"description":"The answering source's reference for the check, for tracing a dispute with the source."},"id_number":{"type":["object","null"],"description":"The ID number's last digits; the number itself is never stored. Null for vNIN and AML checks.","properties":{"type":{"type":"string","enum":["nin","bvn"]},"last_digits":{"type":"string","description":"Last 4 digits (last 2 for checks made through a verify link)."}}},"match":{"type":["object","null"],"additionalProperties":{"type":"integer","minimum":0,"maximum":100}},"match_result":{"type":["object","null"],"description":"A result per field in `match`: match (95+), partial (50–94) or no_match for the fields you sent; high (80+), medium (60–79) or low for face and liveness.","additionalProperties":{"type":"string","enum":["match","partial","no_match","high","medium","low"]}},"route":{"type":"array","items":{"$ref":"#/components/schemas/RouteStep"}},"latency_ms":{"type":["integer","null"]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"}}},"cost":{"type":"object","properties":{"billed":{"type":"boolean"},"amount_kobo":{"type":"integer"},"currency":{"const":"NGN"}}},"customer":{"type":"object","properties":{"id":{"type":"string"},"customer_ref":{"type":["string","null"]}}},"purpose":{"type":"string"},"consent_ref":{"type":["string","null"]},"mode":{"type":"string","enum":["test","live"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"screening":{"type":"object","description":"aml_screen only.","properties":{"clear":{"type":["boolean","null"]},"hits":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"score":{"type":"integer"},"topics":{"type":"array","items":{"type":"string"}},"lists":{"type":"array","items":{"type":"string"}},"dob":{"type":"string"},"country":{"type":"string"},"ref":{"type":"string"}}}}}},"retry":{"type":["object","null"],"properties":{"automatic":{"type":"boolean"},"attempts":{"type":"integer"},"next_at":{"type":"string"},"until":{"type":"string"}}}}},"CheckResult":{"allOf":[{"$ref":"#/components/schemas/Check"},{"type":"object","properties":{"data":{"type":["object","null"],"description":"Record fields: only for approved businesses, from sources that allow it. Never stored."},"data_policy":{"type":"string","enum":["records","match_only","source_match_only","not_stored"]}}}]},"Link":{"type":"object","properties":{"id":{"type":"string","description":"lnk_… (ID number) or vlk_… (face)"},"object":{"type":"string","enum":["link"]},"kind":{"type":"string","enum":["match","face"]},"steps":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["test","live"]},"check":{"type":"string","description":"ID number links only."},"purpose":{"type":"string"},"id_method":{"type":"string","description":"Face links only: nin, document or either."},"customer_ref":{"type":["string","null"]},"name":{"type":["string","null"]},"status":{"type":"string","enum":["pending","opened","completed","cancelled","expired"]},"attempts":{"type":"integer","maximum":3},"opened_at":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"expires_at":{"type":"string"},"created_at":{"type":"string"},"redirect_url":{"type":["string","null"],"description":"Face links."},"result":{"oneOf":[{"$ref":"#/components/schemas/Check"},{"$ref":"#/components/schemas/FaceResult"},{"type":"null"}],"description":"ID number links: the check. Face links: FaceResult."}}},"FaceResult":{"type":"object","description":"Match-first: outcomes and hints, never record fields or face images.","properties":{"outcome":{"type":"string","enum":["verified","document_checked","name_review","name_mismatch","not_matched","liveness_failed","document_rejected","owner_denied","locked"]},"passed":{"type":"boolean"},"final":{"type":"boolean","description":"false while a name review is open; you get another verification.completed when it settles."},"id_used":{"type":"string","enum":["nin","document"]},"name_match":{"type":["string","null"]},"nin_hint":{"type":["string","null"],"description":"Last 2 digits."},"owner_confirmed":{"type":["boolean","null"]},"signals":{"type":"array","items":{"type":"string"}},"bvn":{"type":"object","properties":{"outcome":{"type":"string"},"hint":{"type":"string"}}},"document":{"type":"object","properties":{"type":{"type":"string"},"country":{"type":"string"},"number_hint":{"type":"string"},"expiry":{"type":"string"},"status":{"type":"string"}}},"address":{"type":"object","properties":{"line":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"area_tag":{"type":"string"},"area":{"type":"string"},"tagged_by":{"type":"string"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"created_at":{"type":"string"},"link_id":{"type":"string","description":"Present when it came from a link."},"link_kind":{"type":"string","enum":["match","face"]},"data":{"oneOf":[{"$ref":"#/components/schemas/Check"},{"$ref":"#/components/schemas/Link"}],"description":"A check; for face links, the Link with its FaceResult."}}}}}}