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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

Response:

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

---

Validate Session

Validate a session token.

POST /v1/sessions/validate

Request Body:

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

Response:

{
  "success": true,
  "userId": "user_123",
  "businessId": "clxxxxx",
  "callback": "https://yourapp.com/verification-complete",
  "expiresAt": 1705323600000
}

---

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:

{
  "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:

{
  "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"
  }
}

---

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:

{
  "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:

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

Response:

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

---

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