API Overview

The e-verify API is a RESTful service that provides comprehensive identity verification capabilities for South African businesses. Our API is designed to be simple, secure, and compliant with local regulations. It offers a wide range of services including:

• Identity Verification: Access to Home Affairs OVS system for instant ID verification.
• Manual Identity Verification: OCR identity extraction and verification via API.
• Business Verification: CIPC scraping for business registration checks.
• Selfie Liveness & Face Match: Biometric verification using Amazon Rekognition.
• SIM Swap Check: Real-time SIM swap detection across major mobile networks.
• Credit Score Check: TransUnion integration for credit assessment.
• Email Address Validation: Comprehensive email verification.
• Phone Number Validation: Mobile network verification for accurate contact validation.
• Social Media Validation: Optional social media verification for enhanced identity confidence.

Base URL

All API requests should be made to:

https://api.e-verify.co.za/v1

Authentication

e-verify uses API keys for authentication. Include your API key in the X-API-Key header:

X-API-Key: ev_live_1234567890abcdef...

API Key Types

Environment	Prefix	Description
Live	ev_live_	Production environment
Test	ev_test_	Sandbox environment with mock data

Security

Never expose your API keys in client-side code. Always use server-side requests or secure environment variables.

Request Format

All requests must include the Content-Type: application/json header and send data as JSON in the request body.

Example Request

POST /v1/verify HTTP/1.1
Host: api.e-verify.co.za
X-API-Key: ev_live_1234567890abcdef...
Content-Type: application/json

{
  "id_number": "8001015009087",
  "first_name": "John",
  "last_name": "Doe"
}

Response Format

All responses are returned as JSON with a consistent structure:

Success Response

{
  "request_id": "req_1234567890abcdef",
  "status": "processing",
  "message": "Verification request created successfully"
}

Error Response

{
  "error": "Invalid request data",
  "details": [
    "id_number is required",
    "Invalid phone number format"
  ],
  "request_id": "req_1234567890abcdef"
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request - Invalid request data
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Rate Limits

To ensure fair usage and system stability, we implement rate limits:

Plan	Requests per minute	Burst limit
Starter	60	100
Professional	300	500
Enterprise	1000	2000

When you exceed the rate limit, you'll receive a 429 status code with headers indicating when you can retry:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 60

Idempotency

To prevent duplicate processing, you can include an idempotency key in your requests:

Idempotency-Key: unique-key-12345

If you retry a request with the same idempotency key within 24 hours, you'll receive the same response as the original request.

Pagination

List endpoints support pagination using cursor-based pagination:

{
  "data": [...],
  "has_more": true,
  "next_cursor": "cursor_abc123"
}

To get the next page, include the cursor in your request:

GET /v1/verifications?cursor=cursor_abc123&limit=50

Webhooks

e-verify supports webhooks to notify your application when verification results are ready. Configure webhook URLs in your dashboard or include them in individual requests.

Webhook Payload

{
  "event": "verification.completed",
  "request_id": "req_1234567890abcdef",
  "status": "completed",
  "verifications": {
    // Verification results
  },
  "timestamp": "2024-01-15T10:30:02Z"
}

Webhook Security

All webhooks include a signature header for verification:

X-e-verify-Signature: sha256=abc123...

API Endpoints

Core Verification

Method	Endpoint	Description
POST	/verify	Create a verification request
GET	/verify/{request_id}	Get verification status and results
POST	/verify/batch	Batch verification requests

Transaction Monitoring

Method	Endpoint	Description
POST	/transaction/monitor	Monitor a transaction
POST	/transaction/batch-monitor	Batch transaction monitoring
GET	/transaction/alerts	Get transaction alerts

Passkey Authentication

Method	Endpoint	Description
POST	/passkey/register/begin	Begin passkey registration
POST	/passkey/register/complete	Complete passkey registration
POST	/passkey/authenticate/begin	Begin passkey authentication
POST	/passkey/authenticate/complete	Complete passkey authentication

Account Management

Method	Endpoint	Description
GET	/account	Get account information
GET	/usage	Get API usage statistics
GET	/api-keys	List API keys

SDKs and Libraries

We provide official SDKs for popular programming languages:

• JavaScript/Node.js: npm install @e-verify/node
• Python: pip install e-verify
• PHP: composer require e-verify/php-sdk
• Java: Available on Maven Central
• C#/.NET: Available on NuGet

JavaScript SDK Example

import { e-verify } from '@e-verify/node';

const client = new e-verify(\'ev_live_...\');

const result = await client.verify({
  id_number: \'8001015009087\',
  first_name: \'John\',
  last_name: \'Doe\'
});

Testing

Use our test environment to develop and test your integration:

• Base URL: https://api-test.e-verify.co.za/v1
• API Key: Use keys with ev_test_ prefix
• Mock Data: Returns realistic but fake verification results

Test ID Numbers

Use these test ID numbers for different scenarios:

ID Number	Scenario
8001015009087	Successful verification
8001015009088	No match found
8001015009089	PEP match
8001015009090	Sanctions match
8001015009091	High fraud risk

Compliance and Security

Data Protection

• All data is encrypted in transit (TLS 1.3) and at rest (AES-256)
• We are POPIA and GDPR compliant
• Data retention policies align with regulatory requirements
• Regular security audits and penetration testing

Regulatory Compliance

• FICA: Full compliance with Customer Due Diligence requirements
• AML Act: Anti-Money Laundering screening and monitoring
• POPIA: Protection of Personal Information Act compliance
• FATF: Financial Action Task Force recommendations

Support and Resources

• API Status: status.e-verify.co.za
• Postman Collection: Download here
• OpenAPI Spec: Download here
• Support: support@e-verify.co.za

---

Ready to start building? Check out our Quick Start Guide or explore specific API endpoints.