Voter's CardPreview

Verify a voter's card against the INEC record. Sandbox only until the INEC data agreement is live.

Verifies the document against the INEC record and reports whether it has expired. This product is in preview: it works with sandbox keys while the INEC data agreement is finalized.

POST/v1/verify/voters-card

Availability: Preview (sandbox only)
Indicative price: ₦150.00 per completed check
Consent: Your attestation (client_attested).

Preview

Voter's Card answers with sandbox keys only. Live keys receive 403 product_not_live until the provider agreement is live.

Request

Body parameters

vinstringrequired
Format: 19 letters or digits.
reasonstringrequired
Purpose of the check. One of the 38 NIMC purpose codes. See the purpose code list.
consentobjectrequired
Your attestation that you obtained the data subject's consent for this purpose.
consent.obtainedbooleanrequired
Always true.
matchobject
Optional values to compare against the record. Each comparison is returned in field_matches; match is true only if all of them agree.
match.first_namestring
Must not be empty.
match.middle_namestring
Must not be empty.
match.last_namestring
Must not be empty.
match.date_of_birthstring
Format: date, YYYY-MM-DD.

match is false when the document has expired.

Send an Idempotency-Key header so a retried request is never billed twice. See Idempotency.

curl -X POST http://localhost:4000/v1/verify/voters-card \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "vin": "90F5B1A2C3D4E5F6071",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}'

Response

A completed check returns 200 with a verification object. status is verified or not_found. If the provider has not answered in time you get 202 with status: "pending"; retrieve it later or wait for the verification.completed webhook.

200 OK · assertion

{
  "reference_id": "spm_8171f3a87cbe221341f7185f",
  "object": "verification",
  "product": "voters_card",
  "method": "voters_card",
  "status": "verified",
  "match": true,
  "field_matches": null,
  "field_confidence": null,
  "mode": "sandbox",
  "reason": "financialProducts",
  "subject": "***************6071",
  "summary": {
    "first_name": "A*****",
    "last_name": "O*****",
    "document_type": "voters_card",
    "expired": false,
    "expires_at": null
  },
  "consent": {
    "mechanism": "client_attested",
    "consent_id": null,
    "timestamp": "2026-10-19T09:41:07.512Z"
  },
  "source": "api",
  "error": null,
  "billing": {
    "amount_kobo": 0,
    "currency": "NGN"
  },
  "latency_ms": 330,
  "created_at": "2026-10-19T09:41:07.512Z",
  "updated_at": "2026-10-19T09:41:07.874Z"
}

summary

first_namestring
First name on the record, masked to its first letter: A*****.
last_namestring
Last name on the record, masked to its first letter.
document_typestring
Document type.
expiredboolean
Whether the expiry date has passed.
expires_atstring | null
Expiry date, YYYY-MM-DD; null for documents without expiry.

Full-tier accounts calling the REST API also receive provider, provider_reference and data, the normalized record. MCP, webhooks, lists and bulk results never include it. See Response shaping.

Full tier only

{
  "provider": "sandbox",
  "provider_reference": "SBX6CB753DB2C",
  "data": {
    "document_type": "voters_card",
    "document_number": "90F5B1A2C3D4E5F6071",
    "first_name": "CLARKE",
    "middle_name": "ELIZA",
    "last_name": "GRIFFIN",
    "date_of_birth": "1992-04-18",
    "gender": "female",
    "issued_at": "2022-11-15",
    "expires_at": null,
    "expired": false,
    "issuing_authority": "Independent National Electoral Commission",
    "polling_unit": "PU 012, Eti-Osa",
    "state": "Lagos",
    "lga": "Eti-Osa",
    "photo": null
  }
}

Test values

Send these bodies with a sandbox key. More outcome triggers are on the Sandbox page.

Valid document

{
  "vin": "90F5B1A2C3D4E5F6071",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}

Not found

{
  "vin": "00F0B0A0C0D0E0F0000",
  "reason": "financialProducts",
  "consent": {
    "obtained": true
  }
}

Errors

Status	Code	Meaning
400	`invalid_request`	The body failed validation. `details` lists each field.
401	`unauthorized`	Missing or invalid API key.
402	`insufficient_balance`	Live only: wallet balance is below the check price.
403	`not_entitled`	Your workspace is not enabled for this product or method.
403	`product_not_live`	Live keys: this product is sandbox only for now.
409	`idempotency_key_reused`	The `Idempotency-Key` was used with a different body.
422	`provider_rejected_request`	The upstream registry rejected the request.
503	`verification_unavailable`	Temporary failure. Retry, with the same or a new `Idempotency-Key`.

All errors share one shape. See Errors for the full list.

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