Not for passive liveness: send any JPEG as Base64 or an https URL. Active liveness needs the Capture SDK or the hosted capture page.

Can I run liveness without a BVN?

Yes. Omit the BVN for liveness only; add it for the N-Face comparison with the BVN photo.

Which challenges are used?

A centred face, then three at random from turn left, turn right, look up, look down, smile and move closer. Opposite turns are never issued back to back.

Biometrics & documents

Face liveness and BVN photo match

Passive liveness on one selfie with an optional BVN photo match, or active liveness with random challenges and a server nonce via the Capture SDK.

Create an account Read the docs

What it does

Face Liveness & Match, in detail.

Passive: one selfie, two answers

POST /v1/verify/face checks liveness and, given a BVN, compares the face with the BVN photo through NIBSS N-Face.

Active: challenges with a nonce

Random challenges and a 16-byte nonce; frames are checked for timing, one consistent face, completion, quality and replay.

Every check must pass

liveness_score blends eight checks, but a pass needs all eight, and each session is single-use.

1:N duplicate faces

Liveness frames and selfies are searched for duplicates within your workspace, on by default.

Methods

Every method returns the same normalized verification object. The method, consent mechanism and purpose code are stored with each result.

Method	Input	Returns	Consent	Access
passive	Base64 selfie (or an https URL with image_type url), reason, optional bvn	liveness_passed, face_match_passed, confidences	The selfie is the consent	All approved workspaces
active	Liveness session id, challenge frames, best frame, nonce	liveness_passed, liveness_score, per-check results	The session is the consent	All approved workspaces

passive
Input
Base64 selfie (or an https URL with image_type url), reason, optional bvn
Returns
liveness_passed, face_match_passed, confidences
Consent
The selfie is the consent
Access
All approved workspaces
active
Input
Liveness session id, challenge frames, best frame, nonce
Returns
liveness_passed, liveness_score, per-check results
Consent
The session is the consent
Access
All approved workspaces

How it works

From request to decision.

1
Create a session (active)
POST /v1/liveness/sessions returns the challenges, a nonce, a capture_url and an SDK token.
2
Capture
Mount the Capture SDK with the token, or send the subject the capture_url.
3
Read the verdict
Poll GET /v1/liveness/sessions/{id} or wait for verification.completed; passive checks call POST /v1/verify/face directly.

Routing and providers

Passive liveness and BVN photo comparison use NIBSS N-Face. Active liveness runs on Speedmap’s own anti-spoof pipeline and can add an N-Face comparison when a BVN is supplied.

Use it

One request. One normalized response.

Call POST /v1/verify/face through @speedmap/node, speedmap for Python, or the face_match tool in Speedmap Connect.

Read the guide API reference

Request

curl -X POST http://localhost:4000/v1/verify/face \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "image": "<base64 selfie>",
  "bvn": "22222222221",
  "reason": "financialProducts"
}'

Response · 200 OK

{
  "reference_id": "spm_63f49c0cefc8d0448da85543",
  "object": "verification",
  "product": "face",
  "method": "face_liveness_match",
  "status": "verified",
  "match": true,
  "mode": "sandbox",
  "subject": "*******2221",
  "summary": {
    "liveness_passed": true,
    "liveness_confidence": 0.918,
    "liveness_quality": 0.964,
    "face_match_passed": true,
    "face_match_confidence": 0.938,
    "face_match_quality": 0.986,
    "session_code": "dd58120f-3b09-4e62-b9de-adfcf3de7b67",
    "thresholds": {
      "liveness": 0.6,
      "face_match": 0.9
    }
  }
}

Use cases

Where Nigerian teams use it.

Account opening

Bind a new account to the BVN owner at signup with a single selfie.

Step-up before a large transfer

Run active liveness before a high-value transfer, a device change or a limit increase.

Driver onboarding

Active liveness and a licence check on the driver’s own phone, in five languages.

Policy issuance

Match the applicant to the BVN photo and catch duplicate faces across policies.

Part of:Lending Insurance

What you get back

The fields you will read.

Field	Meaning
summary.liveness_passed	Overall verdict
summary.liveness_score	Active: weighted blend of nonce, timing, single_face, challenges, identity_consistency, quality, replay and passive_liveness
summary.liveness_confidence	Passive: N-Face liveness confidence, with the thresholds applied
summary.face_match_passed / face_match_confidence	Passive: comparison with the BVN photo when a BVN was supplied
summary.checks	Active: pass flag and 0–1 score per check
summary.duplicate_faces	Active and selfie checks: count and references of matching faces already in your workspace
summary.session_id / session_code	Audit handle (active session id, or the passive N-Face session code)

summary.liveness_passed
Meaning
Overall verdict
summary.liveness_score
Meaning
Active: weighted blend of nonce, timing, single_face, challenges, identity_consistency, quality, replay and passive_liveness
summary.liveness_confidence
Meaning
Passive: N-Face liveness confidence, with the thresholds applied
summary.face_match_passed / face_match_confidence
Meaning
Passive: comparison with the BVN photo when a BVN was supplied
summary.checks
Meaning
Active: pass flag and 0–1 score per check
summary.duplicate_faces
Meaning
Active and selfie checks: count and references of matching faces already in your workspace
summary.session_id / session_code
Meaning
Audit handle (active session id, or the passive N-Face session code)

Assertion tier

Scores, flags and session handles only. No frames are returned.

Full tier

Full-tier workspaces can open the best frame and the stored session in the dashboard, with every access audited.

Pricing

Passive face (with or without BVN match) and active liveness are priced separately. A failed capture that never produces a verdict is not billed. Billed per live check on the Scale up plan. Failed calls and idempotent retries are never billed.

Documentation See pricing plans

FAQ

Face Liveness & Match questions.

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

Do I need the SDK?: Not for passive liveness: send any JPEG as Base64 or an https URL. Active liveness needs the Capture SDK or the hosted capture page.
Can I run liveness without a BVN?: Yes. Omit the BVN for liveness only; add it for the N-Face comparison with the BVN photo.
Which challenges are used?: A centred face, then three at random from turn left, turn right, look up, look down, smile and move closer. Opposite turns are never issued back to back.

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