Skip to content
Docs

Quickstart

Create an account and verify a test NIN in about two minutes. No contract, card or approval needed.

View as Markdown

Everything on this page uses the sandbox. Sandbox keys start with sk_test_, return deterministic test data and are never billed.

  1. 1. Create an account

    Sign up with your work email. A sandbox workspace is created for you straight away, with every product enabled on test data.

  2. 2. Copy your test key

    Your first test key is shown right after you create your account, once. Store it in your secret manager or a local .env file: Speedmap keeps only a hash and cannot show it again. You can create more keys in Dashboard → API keys.

    .env
    SPEEDMAP_API_KEY=sk_test_...

  3. 3. Verify a test NIN

    Verify the sandbox identity Clarke Griffin with her NINAuth share code SPM001. The share code is the subject's consent, so this method is open to every business. The match object is optional: Speedmap compares each field against the NIMC record and reports the result per field.

    curl -X POST http://localhost:4000/v1/verify/nin \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "method": "share_code",
  "share_code": "SPM001",
  "reason": "financialProducts",
  "match": {
    "first_name": "Clarke",
    "last_name": "Griffin"
  }
}'

  4. 4. Read the response

    A completed check returns 200 with an assertion. status is verified (the record exists) or not_found; match is true only when every field you supplied agrees with the record. Names in summary are masked, and subject is the masked identifier.

    200 OK
    {
  "reference_id": "spm_8171f3a87cbe221341f7185f",
  "object": "verification",
  "product": "nin",
  "method": "nin_sharecode",
  "status": "verified",
  "match": true,
  "field_matches": {
    "first_name": true,
    "last_name": true
  },
  "field_confidence": {
    "last_name": 100
  },
  "mode": "sandbox",
  "reason": "financialProducts",
  "subject": null,
  "summary": {
    "first_name": "A*****",
    "last_name": "O*****"
  },
  "consent": {
    "mechanism": "ninauth_share_code",
    "consent_id": null,
    "timestamp": "2026-10-19T09:41:07.512Z"
  },
  "source": "api",
  "error": null,
  "billing": {
    "amount_kobo": 0,
    "currency": "NGN"
  },
  "latency_ms": 412,
  "created_at": "2026-10-19T09:41:07.512Z",
  "updated_at": "2026-10-19T09:41:07.874Z"
}

Keep the reference_id. It is the permanent handle for this check: use it to retrieve the verification, reconcile webhooks and raise disputes.

Try other outcomes

The sandbox answers specific inputs with specific outcomes. With method: "nin" (raw NIN lookup) you can try these:

NINOutcome
98765432109Verified: Clarke Griffin
09876543210Verified: Bellamy Blake
00000000000not_found (200, match: false)
99999999999Provider timeout: 202 with status: "pending", resolved on the next GET

Raw NIN lookup is restricted by NIMC to financial institutions and government agencies, so it needs the raw-NIN entitlement on your workspace; without it the request fails with 403 not_entitled. Send the same NINs with method: "in_person" and a selfie_image instead. The full list for every product is on the Sandbox page.

Next steps

  • Choose a NIN verification method for production: in_person (selfie), share_code, or nin if you are eligible for raw lookup.
  • Add an Idempotency-Key to every POST so retries are safe.
  • Subscribe to webhooks instead of polling for pending checks.
  • When you are ready for real data, request go-live in the dashboard. Live keys (sk_live_) are issued after approval. See Authentication.

The base URL for every request is http://localhost:4000.

Questions? Email developers@speedmap.ng. This page is also available as Markdown.