API reference · v1

Globba Verify API

One REST endpoint checks what your customer tells you against national identity records and returns match results. Requests and responses are JSON over HTTPS. The base URL is https://verify.globbahq.com/v1.

Overview

• You send an identity number (NIN or BVN), the details your customer gave you, the purpose, and their consent.
• We compare those details with the record and return exact, partial or none for each name, and true/false for the date of birth.
• The record itself is never returned or stored. Identity numbers are kept only as a keyed hash plus their last two digits.

Authentication

Send your secret key as a bearer token: Authorization: Bearer gv_test_…. Create and revoke keys in the dashboard. A key is shown once, when you create it. Keep keys on your server, never in an app or a browser.

Test and live

Keys starting gv_test_ run in test mode: free, answered from the test identities, never touching real records. Keys starting gv_live_ check real records and are charged. Live keys work once your business is approved and the check type is enabled on your account. Each mode only sees its own verifications.

Create a verification

POST /v1/identity/verifications

curl https://verify.globbahq.com/v1/identity/verifications \
  -H "Authorization: Bearer gv_test_…" \
  -H "Idempotency-Key: onboarding-8841-nin" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "NIN",
    "identifier": "70000000001",
    "subject": {
      "first_name": "Ada",
      "last_name": "Obi",
      "date_of_birth": "1994-02-11"
    },
    "purpose": "customer_onboarding",
    "consent": {
      "reference": "consent-8841",
      "method": "in_app",
      "obtained_at": "2026-11-04T09:40:12+01:00"
    },
    "customer_reference": "customer-8841"
  }'

Reading the result

{
  "id": "ver_MHK3Q2A1x9Lm4TqR",
  "object": "verification",
  "mode": "test",
  "type": "NIN",
  "status": "completed",
  "outcome": "verified",
  "result": {
    "record_found": true,
    "first_name": "exact",
    "last_name": "exact",
    "date_of_birth": true
  },
  "identifier_last2": "01",
  "purpose": "customer_onboarding",
  "consent": { "reference": "consent-8841", "method": "in_app", "obtained_at": "2026-11-04T08:40:12.000Z" },
  "customer_reference": "customer-8841",
  "billable": false,
  "price": { "amount_kobo": 0, "currency": "NGN" },
  "error": null,
  "created_at": "2026-11-04T08:40:13.204Z"
}

A partial name is a close spelling (for example a missing letter). Decide in your own flow whether partial is enough. date_of_birth is null when you didn’t send one, or when the source didn’t check it.

Retrieve and list

GET /v1/identity/verifications/{id} returns one verification.

GET /v1/identity/verifications?limit=20&starting_after=ver_… lists them newest first. limit is 1–100; pass the last id you received as starting_after for the next page while has_more is true.

Consent and purpose

You must have your customer’s consent for each check, for the purpose you send, and keep your own record of it. The consent object tells us which record that is. We refuse requests whose consent is missing, dated in the future, or older than 90 days, and requests for a purpose your account isn’t approved for. Never check someone who hasn’t agreed to it.

Idempotency

Every POST needs an Idempotency-Key header, unique per check (8–128 letters, digits, . _ : -). Sending the same key with the same body returns the first result again, with Idempotent-Replayed: true, and is never charged twice. The same key with a different body is refused with 409 idempotency_conflict.

Billing

Live checks are paid from your prepaid balance at your agreed price per check. found and not_found answers are charged; provider_error answers are not, and any amount held for them is returned at once. With too little balance the API answers 402 insufficient_balance; top up and retry with the same Idempotency-Key.

Errors

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is not valid.",
    "details": [{ "param": "identifier", "message": "Must be 11 digits" }],
    "request_id": "req_4k2PZr0aQe9mT1xY"
  }
}

Every response carries a Request-Id header. Quote it when you contact us.

Rate limits

Each key may make a set number of requests a minute. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Ask us if you need more.

Test identities

With a gv_test_ key, these numbers give fixed answers. Any other number is not_found.

Send a different name or date of birth with a found number to see partial, none and not_verified.