Skip to content
Speedmap
Create an account

Workflow

Hosted verification links

Create a session, send the url, and Speedmap runs NIN, face, BVN, document or liveness steps on its own pages, with results by webhook.

Create an account Read the docs

What it does

Hosted Verification Links, in detail.

One POST, one url

Send the url by SMS, email, WhatsApp or QR code, or redirect to it from your app.

Two kinds of session

Verification sessions run nin_in_person, face, bvn_boolean or document number; capture sessions run liveness, document and selfie.

Your brand, five languages

Capture sessions take your name, logo and colour, and a locale of en, pcm, ha, yo or ig.

Attempt limits and expiry

Verification sessions allow three attempts per step and 30 requests a minute, and last five minutes to seven days.

How it works

From request to decision.

  1. 1

    Create the session

    POST /v1/verification-sessions with products and purpose, or POST /v1/capture-sessions with steps, locale and brand.

  2. 2

    Send the url

    The token is shown once and stored as a hash; success_url brings the customer back.

  3. 3

    Receive the result

    Handle the completed webhook or read GET /v1/verification-sessions/{id} for each step and the result.

Routing and providers

Hosted pages run on speedmap.ng and call the same products as the API, and each step is a normal verification with a reference_id. Up to 20 metadata keys come back on the webhook.

Use it

One request. One normalized response.

Call POST /v1/verification-sessions through @speedmap/node, speedmap for Python.

Read the guide API reference
Request
curl -X POST http://localhost:4000/v1/verification-sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "products": [
    "nin_in_person",
    "bvn_boolean"
  ],
  "reason": "financialProducts",
  "subject": {
    "name": "Clarke Griffin",
    "phone": "08031234567"
  },
  "success_url": "https://app.example.com/kyc/done",
  "metadata": {
    "application_id": "LA-2291"
  },
  "expires_in_minutes": 1440
}'
Response · 201 Created
{
  "id": "vs_f716af0b95f101c2",
  "object": "verification_session",
  "status": "created",
  "mode": "sandbox",
  "products": [
    "nin_in_person",
    "bvn_boolean"
  ],
  "reason": "financialProducts",
  "subject": {
    "name": "Clarke Griffin",
    "email": null,
    "phone": "*******4567"
  },
  "success_url": "https://app.example.com/kyc/done",
  "metadata": {
    "application_id": "LA-2291"
  },
  "steps": [],
  "completed_steps": [],
  "result": null,
  "expires_at": "2026-10-21T12:54:54.128Z",
  "url": "https://speedmap.ng/verify/lMOM5-rg8ft7EmnqZmFJ1mi8_mqIyiSvsfIEYVQY37c"
}

Use cases

Where Nigerian teams use it.

Lending without an app

Send the link in the loan offer SMS; the borrower verifies on any phone.

Workforce onboarding

Create sessions for a cohort of hires or riders and track completion in the dashboard.

Insurance claims

Verify the claimant with a selfie-to-BVN check before the adjuster calls.

Agent-assisted onboarding

The agent generates a QR code; the customer completes the flow on their own device.

Part of:MarketplacesHR & gig platforms

What you get back

The fields you will read.

  • status

    Meaning
    Verification sessions: created, started, completed, abandoned or expired

  • result

    Meaning
    passed when every step verified and matched, otherwise failed; null until completed

  • steps[] / verifications

    Meaning
    The reference_id, status and match for every step (capture sessions return the verification for each step, keyed by step)

  • metadata

    Meaning
    Your own keys, echoed on the webhook

Assertion tier

Session objects contain assertions only.

Full tier

Open any step’s reference in the dashboard or API for the record, subject to your tier.

Pricing

No charge for the session; you pay for the verifications it completes.

DocumentationSee pricing plans

FAQ

Hosted Verification Links questions.

Need more detail? Read the documentation or talk to our team.

Can I put my logo and colours on the page?
Yes for capture sessions, through the brand object. Verification sessions use Speedmap’s neutral page today.
Which languages are available?
Capture sessions run in English, Pidgin, Hausa, Yorùbá and Igbo, set with locale.
How long can a link stay valid?
Verification sessions from 5 minutes to 7 days; capture sessions from 5 minutes to 24 hours.

Start verifying in minutes. Go live when you’re ready.

Create your account in under a minute and explore the full dashboard. We switch your workspace live after a short compliance review.

Create an account Read the quickstart