Identity Verification API

The core verification API allows you to verify South African identities using multiple data sources including DHA, mobile networks, and fraud detection systems.

Create Verification Request

Create a new identity verification request.

Endpoint

POST /v1/verify

Request Body

Field	Type	Required	Description
`id_number`	string	No*	South African ID number (13 digits)
`first_name`	string	No	First name to verify
`last_name`	string	No	Last name to verify
`date_of_birth`	string	No	Date of birth (YYYY-MM-DD format)
`phone_number`	string	No*	South African phone number
`email`	string	No*	Email address
`company_registration`	string	No	CIPC registration number
`webhook_url`	string	No	URL to receive verification results

*At least one of id_number, phone_number, or email is required.

Example Request

{
  "id_number": "8001015009087",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1980-01-01",
  "phone_number": "+27821234567",
  "email": "john.doe@example.com",
  "webhook_url": "https://your-app.com/webhook"
}

Response

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

cURL Example

curl -X POST https://api.verifyza.com/v1/verify \
  -H "X-API-Key: vza_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "id_number": "8001015009087",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+27821234567",
    "webhook_url": "https://your-app.com/webhook"
  }'

Get Verification Results

Retrieve the status and results of a verification request.

Endpoint

GET /v1/verify/{request_id}

Path Parameters

Parameter	Type	Description
`request_id`	string	The verification request ID

Response

{
  "request_id": "req_1234567890abcdef",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:02Z",
  "verifications": {
    "dha": {
      "status": "verified",
      "match_score": 98.5,
      "verified_data": {
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1980-01-01"
      }
    },
    "cipc": {
      "status": "not_found",
      "company_name": null,
      "directors": null
    },
    "mno": {
      "status": "verified",
      "network": "vodacom",
      "match_score": 95.2
    },
    "pep_sanctions": [
      {
        "screening_type": "pep",
        "status": "clear",
        "risk_score": 0,
        "matches": []
      },
      {
        "screening_type": "sanctions",
        "status": "clear",
        "risk_score": 0,
        "matches": []
      }
    ],
    "watchlist": {
      "status": "clear",
      "risk_score": 0,
      "matches": []
    },
    "fraud_graph": [
      {
        "entity_type": "person",
        "entity_value": "8001015009087",
        "risk_score": 15.3,
        "connections": [
          {
            "connection_type": "shared_device",
            "connected_entity": {
              "type": "device",
              "value": "device_123456"
            },
            "strength": 0.8,
            "first_seen": "2024-01-10",
            "last_seen": "2024-01-15"
          }
        ],
        "flags": []
      }
    ]
  }
}

Status Values

Status	Description
`processing`	Verification is in progress
`completed`	Verification completed successfully
`failed`	Verification failed due to an error

Verification Results

DHA Verification

Field	Type	Description
`status`	string	`verified`, `no_match`, `partial_match`, `error`
`match_score`	number	Confidence score (0-100)
`verified_data`	object	Verified personal information

MNO Verification

Field	Type	Description
`status`	string	`verified`, `no_match`, `error`
`network`	string	Mobile network (`vodacom`, `mtn`, `cell_c`, `telkom`)
`match_score`	number	Confidence score (0-100)

PEP/Sanctions Screening

Field	Type	Description
`screening_type`	string	`pep`, `sanctions`, `adverse_media`
`status`	string	`clear`, `matches_found`, `error`
`risk_score`	number	Risk score (0-100)
`matches`	array	Array of matching records

Fraud Graph Analysis

Field	Type	Description
`entity_type`	string	`person`, `device`, `email`, `phone`
`entity_value`	string	The entity value being analyzed
`risk_score`	number	Fraud risk score (0-100)
`connections`	array	Connected entities and relationships
`flags`	array	Risk flags and anomalies

cURL Example

curl -X GET https://api.verifyza.com/v1/verify/req_1234567890abcdef \
  -H "X-API-Key: vza_live_1234567890abcdef..."

Batch Verification

Process multiple verification requests in a single API call for improved efficiency.

Endpoint

POST /v1/verify/batch

Request Body

Field	Type	Required	Description
`requests`	array	Yes	Array of verification requests (max 100)

Example Request

{
  "requests": [
    {
      "id_number": "8001015009087",
      "first_name": "John",
      "last_name": "Doe"
    },
    {
      "id_number": "8502020010088",
      "first_name": "Jane",
      "last_name": "Smith"
    }
  ]
}

Response

{
  "batch_id": "batch_1234567890abcdef",
  "total_requests": 2,
  "results": [
    {
      "request_id": "req_1234567890abcdef",
      "status": "processing"
    },
    {
      "request_id": "req_0987654321fedcba",
      "status": "processing"
    }
  ]
}

Batch Pricing

Batch requests receive automatic volume discounts:

10+ requests: 10% discount
50+ requests: 15% discount
100+ requests: 20% discount

cURL Example

curl -X POST https://api.verifyza.com/v1/verify/batch \
  -H "X-API-Key: vza_live_1234567890abcdef..." \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "id_number": "8001015009087",
        "first_name": "John",
        "last_name": "Doe"
      },
      {
        "id_number": "8502020010088",
        "first_name": "Jane",
        "last_name": "Smith"
      }
    ]
  }'

Error Handling

Common Errors

Error Code	Description	Solution
`INVALID_ID_NUMBER`	Invalid South African ID number format	Ensure ID number is 13 digits and passes Luhn check
`INVALID_PHONE_NUMBER`	Invalid phone number format	Use South African format (+27, 27, or 0 prefix)
`MISSING_REQUIRED_FIELD`	Required field is missing	Include at least one of: id_number, phone_number, email
`VERIFICATION_FAILED`	Verification service unavailable	Retry the request or contact support
`RATE_LIMIT_EXCEEDED`	Too many requests	Implement exponential backoff

Error Response Example

{
  "error": "INVALID_ID_NUMBER",
  "message": "Invalid South African ID number format",
  "details": [
    "ID number must be exactly 13 digits",
    "ID number failed Luhn algorithm validation"
  ],
  "request_id": "req_1234567890abcdef"
}

Webhooks

Configure webhooks to receive verification results automatically instead of polling.

Webhook Payload

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

Webhook Events

Event	Description
`verification.completed`	Verification completed successfully
`verification.failed`	Verification failed
`verification.partial`	Partial verification results available

Webhook Security

Verify webhook authenticity using the signature header:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === `sha256=${expectedSignature}`;
}

SDK Examples

JavaScript/Node.js

import { VerifyZA } from '@verifyza/node';

const client = new VerifyZA('vza_live_...');

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

// Get results
const verification = await client.getVerification(result.request_id);

Python

from verifyza import VerifyZA

client = VerifyZA('vza_live_...')

# Single verification
result = client.verify(
    id_number='8001015009087',
    first_name='John',
    last_name='Doe'
)

# Get results
verification = client.get_verification(result['request_id'])

PHP

use VerifyZA\Client;

$client = new Client('vza_live_...');

// Single verification
$result = $client->verify([
    'id_number' => '8001015009087',
    'first_name' => 'John',
    'last_name' => 'Doe'
]);

// Get results
$verification = $client->getVerification($result['request_id']);

Best Practices

Performance Optimization

Use batch requests for multiple verifications
Implement webhooks instead of polling
Cache results when appropriate
Use idempotency keys for retry logic

Security

Never expose API keys in client-side code
Use HTTPS for all webhook endpoints
Verify webhook signatures to ensure authenticity
Implement rate limiting in your application

Error Handling

Implement exponential backoff for retries
Handle partial verification results gracefully
Log errors for debugging and monitoring
Provide fallback mechanisms for critical flows

Need help with integration? Check our Quick Start Guide or contact support at support@verifyza.com.

Create Verification Request​

Endpoint​

Request Body​

Example Request​

Response​

cURL Example​

Get Verification Results​

Endpoint​

Path Parameters​

Response​

Status Values​

Verification Results​

DHA Verification​

MNO Verification​

PEP/Sanctions Screening​

Fraud Graph Analysis​

cURL Example​

Batch Verification​

Endpoint​

Request Body​

Example Request​

Response​

Batch Pricing​

cURL Example​

Error Handling​

Common Errors​

Error Response Example​

Webhooks​

Webhook Payload​

Webhook Events​

Webhook Security​

SDK Examples​

JavaScript/Node.js​

Python​

PHP​

Best Practices​

Performance Optimization​

Security​

Error Handling​

Create Verification Request

Endpoint

Request Body

Example Request

Response

cURL Example

Get Verification Results

Endpoint

Path Parameters

Response

Status Values

Verification Results

DHA Verification

MNO Verification

PEP/Sanctions Screening

Fraud Graph Analysis

cURL Example

Batch Verification

Endpoint

Request Body

Example Request

Response

Batch Pricing

cURL Example

Error Handling

Common Errors

Error Response Example

Webhooks

Webhook Payload

Webhook Events

Webhook Security

SDK Examples

JavaScript/Node.js

Python

PHP

Best Practices

Performance Optimization

Security

Error Handling