YeboVerify API Reference

Base URL

https://api.yeboverify.com

Authentication

All API endpoints (except health check) require authentication via the X-API-Key header.

X-API-Key: your_api_key_here

Endpoints

Health Check

Check API status and availability.

GET /health

Response:

json

{
  "status": "ok",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "service": "yeboverify-api",
  "version": "1.0.0"
}

Verification Endpoints

Selfie Match Verification

Compare a selfie against a profile picture URL using facial recognition.

POST /v1/verify/selfie-match

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	`multipart/form-data`

Request Body (multipart/form-data):

Field	Type	Required	Description
`selfie`	file	Yes	Selfie image (JPEG, PNG, max 10MB)
`profilePictureUrl`	string	Yes	URL of the profile picture to compare against
`externalRef`	string	No	Your internal reference ID

Response:

json

{
  "success": true,
  "data": {
    "verificationId": "vrf_sm_abc123xyz",
    "samePerson": true,
    "matchScore": 94.5,
    "confidence": "high",
    "processingMs": 2340
  }
}

Response Fields:

Field	Type	Description
`verificationId`	string	Unique verification ID (prefixed with `vrf_sm_`)
`samePerson`	boolean	`true` if faces match (score ≥ 80)
`matchScore`	number	Similarity score (0-100)
`confidence`	string	`high` (≥90), `medium` (75-89), `low` (<75)
`processingMs`	number	Processing time in milliseconds

ID Document Verification

Full identity verification with face matching, liveness detection, and document OCR.

POST /v1/verify/id-document

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	`multipart/form-data`

Request Body (multipart/form-data):

Field	Type	Required	Description
`selfie`	file	Yes	Live selfie image (JPEG, PNG, max 10MB)
`idFront`	file	Yes	Front of ID document (JPEG, PNG, max 10MB)
`idBack`	file	No	Back of ID document (JPEG, PNG, max 10MB)
`externalRef`	string	No	Your internal reference ID
`documentType`	string	No	Document type hint (e.g., `passport`, `national_id`)

Response:

json

{
  "success": true,
  "data": {
    "verificationId": "vrf_id_xyz789abc",
    "status": "approved",
    "decision": "approved",
    "confidence": "high",
    "faceMatch": {
      "score": 92.3,
      "samePerson": true
    },
    "documentData": {
      "surname": "SMITH",
      "names": "JOHN MICHAEL",
      "dateOfBirth": "1990-05-15",
      "idNumber": "9005151234567",
      "sex": "M",
      "nationality": "ZA",
      "documentType": "NATIONAL_ID",
      "expiryDate": "2030-05-15"
    },
    "ocrConfidence": 85,
    "processingMs": 5420
  }
}

Response Fields:

Field	Type	Description
`verificationId`	string	Unique verification ID (prefixed with `vrf_id_`)
`status`	string	`approved`, `rejected`, or `needs_review`
`decision`	string	Same as status
`confidence`	string	`high`, `medium`, or `low`
`faceMatch.score`	number	Face similarity score (0-100)
`faceMatch.samePerson`	boolean	`true` if faces match (score ≥ 70)
`documentData`	object	Extracted document information
`ocrConfidence`	number	OCR confidence (0-100)
`processingMs`	number	Processing time in milliseconds

Document Data Fields:

Field	Type	Description
`surname`	string	Last name from document
`names`	string	First and middle names
`dateOfBirth`	string	Date of birth (YYYY-MM-DD)
`idNumber`	string	ID/Document number
`sex`	string	`M` or `F`
`nationality`	string	Nationality code
`documentType`	string	Type of document
`expiryDate`	string	Document expiry date (YYYY-MM-DD)

Session Endpoints

For redirect-based verification flows.

Create Session

Create a verification session for redirect-based flows.

POST /v1/sessions/create

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	`application/json`

Request Body:

json

{
  "userId": "user_123",
  "callback": "https://yourapp.com/verification-complete"
}

Field	Type	Required	Description
`userId`	string	Yes	Your user identifier
`callback`	string	No	Callback URL after verification
`theme`	object	No	Per-session branding override — see White-Label Branding

Any other top-level field, or any theme sub-field outside logoUrl/companyName/primaryColor/darkMode, is rejected with 400.

Response:

json

{
  "success": true,
  "session": "eyJhbGciOiJIUzI1NiIs...",
  "verifyUrl": "https://verify.yeboverify.com#session=eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}

You deliver the link — YeboVerify does not

This endpoint returns verifyUrl. It does not send it anywhere. YeboVerify never contacts your user: there is no SMS, no email, and no one-time code or OTP issued by this API. Getting the link to your user is your integration's job — redirect their browser to it, render it as a button, or send it over whatever channel you already use.

If your users report "I never received a code", they are waiting on a message YeboVerify was never going to send. Check that your own code actually delivered verifyUrl.

Two constraints when you pass it on:

Keep the #. The token sits in the URL fragment, not the query string, so it never reaches server logs, analytics, or the Referer header of the next page. Rewriting it to ?session= leaks a live credential.
It expires in expiresIn seconds (1800 = 30 min). Mint it when the user is ready to verify, not hours ahead. If a link expires before the user opens it, call this endpoint again for a fresh one.

The verification result comes back to you on your webhook, not on this response — see Webhooks.

Validate Session

Validate a session token.

POST /v1/sessions/validate

Request Body:

json

{
  "session": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

json

{
  "success": true,
  "userId": "user_123",
  "businessId": "clxxxxx",
  "callback": "https://yourapp.com/verification-complete",
  "expiresAt": 1705323600000,
  "branding": { "logoUrl": null, "companyName": null, "primaryColor": null, "darkMode": true }
}

Upload Photo (progressive)

Upload a single photo against a session token. Useful on slow networks — your client uploads each captured photo as soon as it's ready, then calls Submit Session with just the keys instead of bytes.

POST /v1/sessions/upload

Request Body:

json

{
  "session": "eyJhbGciOiJIUzI1NiIs...",
  "photo": "data:image/jpeg;base64,/9j/4AAQ...",
  "type": "selfie"
}

Field	Type	Required	Description
`session`	string	Yes	Session token from Create Session
`photo`	string	Yes	Base64-encoded image (with or without `data:` URL prefix)
`type`	string	Yes	One of `selfie`, `idFront`, `idBack`, `liveness1`, `liveness2`

Response:

json

{
  "success": true,
  "key": "sessions/user_123/selfie-abcd1234efgh",
  "type": "selfie",
  "size": 184320
}

The returned key can be passed to Submit Session instead of re-uploading the bytes.

Submit Session

Submit a verification with photos that were either uploaded progressively (using *Key fields) or sent inline as base64 (using non-Key fields). Triggers AI processing — the result lands in your webhook as verification.completed after ~5–10 seconds. A verification.submitted webhook fires immediately on success.

POST /v1/sessions/submit

Request Body (using progressive upload keys):

json

{
  "session": "eyJhbGciOiJIUzI1NiIs...",
  "selfieKey": "sessions/user_123/selfie-abcd",
  "idFrontKey": "sessions/user_123/idFront-efgh",
  "idBackKey": "sessions/user_123/idBack-ijkl"
}

Request Body (using inline base64):

json

{
  "session": "eyJhbGciOiJIUzI1NiIs...",
  "selfie": "data:image/jpeg;base64,...",
  "idFront": "data:image/jpeg;base64,...",
  "idBack": "data:image/jpeg;base64,..."
}

Field	Type	Required	Description
`session`	string	Yes	Session token from Create Session
`selfie` / `selfieKey`	string	Yes (one of)	Selfie photo
`idFront` / `idFrontKey`	string	Yes (one of)	Front of ID document
`idBack` / `idBackKey`	string	No	Back of ID document (some types only)

Response:

json

{
  "success": true,
  "verificationId": "vrf_id_abc123xyz",
  "status": "PENDING",
  "message": "Verification submitted. Results will be sent via webhook."
}

Listen for the verification.completed webhook to receive the final decision. See Webhooks for details.

Verification History

List Verifications

Get a paginated list of verifications for your business.

GET /v1/verifications

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Query Parameters:

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Results per page (max 100)
`status`	string	-	Filter by status: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `NEEDS_REVIEW`

Response:

json

{
  "success": true,
  "data": {
    "verifications": [
      {
        "verificationId": "vrf_sm_abc123",
        "externalRef": "order_456",
        "status": "COMPLETED",
        "decision": "APPROVED",
        "confidence": "high",
        "createdAt": "2024-01-15T12:00:00.000Z",
        "completedAt": "2024-01-15T12:00:03.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

Get Verification Details

Get detailed information about a specific verification.

GET /v1/verifications/:verificationId

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Response:

json

{
  "success": true,
  "data": {
    "verificationId": "vrf_id_xyz789abc",
    "externalRef": "user_123",
    "status": "COMPLETED",
    "decision": "APPROVED",
    "decisionReason": "High face match and document verification confidence",
    "confidence": "high",
    "faceScore": 92.3,
    "ocrConfidence": 85,
    "extractedData": {
      "surname": "SMITH",
      "names": "JOHN MICHAEL",
      "dateOfBirth": "1990-05-15",
      "idNumber": "9005151234567",
      "documentType": "NATIONAL_ID"
    },
    "processingMs": 5420,
    "createdAt": "2024-01-15T12:00:00.000Z",
    "completedAt": "2024-01-15T12:00:05.000Z"
  }
}

Delete Verification

Remove a verification record. Triggers a verification.deleted webhook so downstream systems (e.g., your KYC store) can reset state for the user. Useful for letting a user re-verify after a rejected decision, or for honouring a "delete my data" request.

DELETE /v1/verifications/:verificationId

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Response:

json

{
  "success": true,
  "message": "Verification deleted"
}

Errors with 404 if the verification doesn't exist or doesn't belong to your business. The associated images are removed from R2 storage immediately as part of the delete.

Account Endpoints

Get Account Info

Get your business account information.

GET /v1/account

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Response:

json

{
  "success": true,
  "data": {
    "id": "clxxxxx",
    "name": "Acme Corp",
    "email": "api@acme.com",
    "webhookUrl": "https://acme.com/webhooks/yeboverify",
    "plan": "business",
    "active": true,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Update Webhook URL

Update your webhook configuration.

PUT /v1/account/webhook

Headers:

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	`application/json`

Request Body:

json

{
  "webhookUrl": "https://yourapp.com/webhooks/yeboverify",
  "webhookSecret": "your_webhook_secret"
}

Response:

json

{
  "success": true,
  "data": {
    "webhookUrl": "https://yourapp.com/webhooks/yeboverify",
    "message": "Webhook configuration updated"
  }
}

Get Branding

Get your hosted-flow branding. See White-Label Branding for the full picture.

GET /v1/settings/branding

Response:

json

{
  "success": true,
  "data": {
    "logoUrl": "https://acme.com/logo.svg",
    "companyName": "Acme Corp",
    "primaryColor": "#FF6B00",
    "darkMode": true
  }
}

Update Branding

Set (or clear, with null) your hosted-flow branding. A field outside logoUrl/companyName/primaryColor/darkMode is rejected with 400.

PUT /v1/settings/branding

Request Body:

json

{
  "logoUrl": "https://acme.com/logo.svg",
  "companyName": "Acme Corp",
  "primaryColor": "#FF6B00",
  "darkMode": true
}

File Requirements

Supported Formats

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)

Size Limits

Maximum file size: 10MB per file
Recommended resolution: 640x480 to 1920x1080

Image Quality Tips

Ensure good lighting
Face should be clearly visible
ID documents should be flat and fully visible
Avoid blur, glare, or shadows

YeboVerify API Reference ​

Base URL ​

Authentication ​

Endpoints ​

Health Check ​

Verification Endpoints ​

Selfie Match Verification ​

ID Document Verification ​

Session Endpoints ​

Create Session ​

Validate Session ​

Upload Photo (progressive) ​

Submit Session ​

Verification History ​

List Verifications ​

Get Verification Details ​

Delete Verification ​

Account Endpoints ​

Get Account Info ​

Update Webhook URL ​

Get Branding ​

Update Branding ​

File Requirements ​

Supported Formats ​

Size Limits ​

Image Quality Tips ​

YeboVerify API Reference

Base URL

Authentication

Endpoints

Health Check

Verification Endpoints

Selfie Match Verification

ID Document Verification

Session Endpoints

Create Session

Validate Session

Upload Photo (progressive)

Submit Session

Verification History

List Verifications

Get Verification Details

Delete Verification

Account Endpoints

Get Account Info

Update Webhook URL

Get Branding

Update Branding

File Requirements

Supported Formats

Size Limits

Image Quality Tips