Biometric Verification

Invite an applicant to complete selfie, liveness, and document capture on a hosted page, then fetch the outcome with the verification UUID.

Overview

You start the check with one call. The applicant finishes on https://verify.peleza.com. Liveness is part of that hosted page, not a separate API. When they are done, fetch the result with the reference from this response.

Authenticate with OAuth client credentials (Bearer token)
POST /api/v1/biometric/invite with the applicant email, name, and consent
Send the applicant the invitation_url (https://verify.peleza.com/biometric/verify/{token})
GET /api/v1/biometric/{reference} with the returned UUID to pull the outcome
An approved result includes applicant, id_docs, and images. Each image has image_id, label, and a /media/identity URL for the national ID and the selfie.
Sandbox uses the same paths with fictional samples. grace.mwangi@peleza.com stays pending. james.kamau@peleza.com returns the approved sample, including images. Any other email is approved on fetch. rejected@peleza.com is rejected.

Loading sandbox test IDs…

Start verification

POST/api/v1/biometric/invite

{{baseUrl}}/api/v1/biometric/invite

Header

Header	Type	Description
Authorization	string	`Bearer YOUR_ACCESS_TOKEN` from the OAuth client-credentials flow
Content-Type	string	application/json

Body Parameters

Parameter	Type	Description	Required
email	string	Applicant email address	required
first_name	string	Applicant first name	required
last_name	string	Applicant last name	required
message	string	Optional note stored with the invitation	optional
consent	boolean	Must be true — confirms data-subject consent to perform this verification	required

Request payload

All verification APIs require consent: true in the JSON body.

Sample dataRequest payload

{
  "email": "john.doe@example.com",
  "first_name": "JOHN DOE",
  "last_name": "JOHN DOE",
  "message": "sample-value",
  "consent": true
}

Expected response

200 OKSample dataExpected response

{
  "success": true,
  "response_code": 200,
  "message": "Verification link created for jane@peleza.com.",
  "data": {
    "verification": {
      "name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@peleza.com",
      "reference": "a1b2c3d4-e5f6-4789-a012-3456789abcde",
      "invitation_url": "https://verify.peleza.com/biometric/verify/aB3dE5fG7hJ9kL2mN4pQ6rS8tU0vW1xY2zA3bC4dE5fG",
      "expires_at": "Oct 21, 2026 15:04"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

Field	Type	Description
success	boolean	Whether the request succeeded
response_code	number	Application response code (typically mirrors HTTP)
message	string	Human-readable status message
data	object	Payload for the verified resource
request_id	string	UUID for support and audit trails
data.verification.reference	string	Verification UUID. Pass this to GET /api/v1/biometric/{reference}.
data.verification.invitation_url	string	Hosted capture link on https://verify.peleza.com. Send this to the applicant.
data.verification.expires_at	string	When the invitation link expires
data.verification.email	string	Applicant email
data.verification.first_name	string	Applicant first name
data.verification.last_name	string	Applicant last name
data.verification.name	string	Applicant full name

Set {{baseUrl}} to https://api.peleza.com (production) or https://sandbox.peleza.com (sandbox). Authenticated calls need a Bearer token from POST /api/v1/oauth/token.