YeboVerify API Routes

Base URL

Production: https://api.yeboverify.com

Authentication

All routes require API key authentication:

X-API-Key: your_api_key_here

---

Admin Routes

Business Registration

Method	Route	Description
POST	/v1/businesses/register	Register new business (admin only)

Body:

{
  "name": "ACME Corp",
  "email": "admin@acme.com",
  "plan": "starter"
}

Response:

{
  "success": true,
  "data": {
    "id": "clx...",
    "name": "ACME Corp",
    "email": "admin@acme.com",
    "apiKey": "ybv_live_abc123...",
    "plan": "starter"
  }
}

---

Account Routes

Get Account

Method	Route	Auth
GET	/v1/account	API Key

Response:

{
  "success": true,
  "data": {
    "id": "clx...",
    "name": "ACME Corp",
    "email": "admin@acme.com",
    "plan": "starter",
    "webhookUrl": "https://your-app.com/webhook",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Update Webhook

Method	Route	Auth
PUT	/v1/account/webhook	API Key

Body:

{
  "webhookUrl": "https://your-app.com/webhook",
  "webhookSecret": "your_secret_here"
}

---

Verification Routes

Submit Verification

Method	Route	Auth
POST	/v1/verify	API Key

Content-Type: multipart/form-data

Fields:

Field	Type	Required	Description
idFront	file	✓	Front of ID document
idBack	file		Back of ID document
selfie	file	✓	User selfie photo
externalRef	string		Your reference ID
documentType	string		Document type hint

Response:

{
  "success": true,
  "data": {
    "verificationId": "vrf_abc123xyz",
    "status": "pending"
  }
}

Get Verification

Method	Route	Auth
GET	/v1/verifications/:verificationId	API Key

Response:

{
  "success": true,
  "data": {
    "verificationId": "vrf_abc123xyz",
    "externalRef": "your-ref-123",
    "status": "completed",
    "decision": "approved",
    "decisionReason": "High face match and OCR confidence",
    "confidence": "high",
    "faceScore": 92.5,
    "ocrConfidence": 85.0,
    "extractedData": {
      "surname": "Doe",
      "names": "John James",
      "dateOfBirth": "1990-05-15",
      "idNumber": "123456789",
      "documentType": "National ID"
    },
    "processingMs": 3250,
    "createdAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:00:03Z"
  }
}

List Verifications

Method	Route	Auth
GET	/v1/verifications	API Key

Query Parameters:

Param	Type	Default	Description
page	number	1	Page number
limit	number	20	Items per page (max 100)
status	string		Filter by status

Response:

{
  "success": true,
  "data": {
    "verifications": [
      {
        "verificationId": "vrf_abc123xyz",
        "externalRef": "your-ref-123",
        "status": "completed",
        "decision": "approved",
        "confidence": "high",
        "createdAt": "2024-01-15T10:00:00Z",
        "completedAt": "2024-01-15T10:00:03Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}

---

Webhook Payload

When a verification completes, YeboVerify sends:

{
  "event": "verification.completed",
  "verificationId": "vrf_abc123xyz",
  "externalRef": "your-ref-123",
  "status": "completed",
  "decision": "approved",
  "confidence": "high",
  "faceScore": 92.5,
  "ocrConfidence": 85.0,
  "extractedData": {
    "surname": "Doe",
    "names": "John James",
    "dateOfBirth": "1990-05-15",
    "idNumber": "123456789",
    "documentType": "National ID"
  },
  "timestamp": "2024-01-15T10:00:03.000Z"
}

Headers:

Content-Type: application/json
X-YeboVerify-Signature: sha256=abc123...

---

Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

Error Codes:

Code	HTTP	Description
INVALID_API_KEY	401	API key invalid or missing
VERIFICATION_NOT_FOUND	404	Verification ID not found
INVALID_FILE	400	File upload issue
PROCESSING_ERROR	500	Internal processing failure