Quick Start Guide

Get up and running with VerifyZA in under 10 minutes! This guide will walk you through making your first identity verification request.

Prerequisites

Before you begin, make sure you have:

• A VerifyZA account (sign up here)
• Your API key (available in your dashboard)
• A development environment with HTTP request capabilities

Step 1: Get Your API Key

1. Sign up for a VerifyZA account at verifyza.com/signup
2. Verify your email address
3. Log in to your dashboard
4. Navigate to API Keys section
5. Copy your API key (it looks like: vza_live_1234567890abcdef...)

Keep Your API Key Secret

Never expose your API key in client-side code or public repositories. Always use environment variables or secure configuration management.

Step 2: Make Your First Request

Let's verify a South African ID number using our DHA integration:

Using cURL

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

Using JavaScript/Node.js

const response = await fetch('https://api.verifyza.com/v1/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.VERIFYZA_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id_number: '8001015009087',
    first_name: 'John',
    last_name: 'Doe',
    webhook_url: 'https://your-app.com/webhook'
  })
});

const result = await response.json();
console.log(result);

Using Python

import requests
import os

url = "https://api.verifyza.com/v1/verify"
headers = {
    "X-API-Key": os.getenv("VERIFYZA_API_KEY"),
    "Content-Type": "application/json"
}
data = {
    "id_number": "8001015009087",
    "first_name": "John",
    "last_name": "Doe",
    "webhook_url": "https://your-app.com/webhook"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)

Using PHP

<?php
$url = 'https://api.verifyza.com/v1/verify';
$headers = [
    'X-API-Key: ' . $_ENV['VERIFYZA_API_KEY'],
    'Content-Type: application/json'
];
$data = [
    'id_number' => '8001015009087',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'webhook_url' => 'https://your-app.com/webhook'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

print_r($result);
?>

Step 3: Understanding the Response

The API will return a response like this:

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

Since verification can take a few seconds, the API works asynchronously. You can:

1. Use webhooks (recommended) - We'll POST the results to your webhook URL
2. Poll for results - Check the status using the request ID

Polling for Results

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

Complete Verification Result

Once processing is complete, you'll receive a comprehensive result:

{
  "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"
      }
    },
    "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": [],
        "flags": []
      }
    ]
  }
}

Step 4: Handle Webhooks (Recommended)

Set up a webhook endpoint to receive verification results automatically:

Express.js Example

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const verification = req.body;
  
  console.log('Verification completed:', verification.request_id);
  console.log('Status:', verification.status);
  
  // Process the verification result
  if (verification.status === 'completed') {
    // Handle successful verification
    processVerificationResult(verification);
  } else if (verification.status === 'failed') {
    // Handle failed verification
    handleVerificationFailure(verification);
  }
  
  // Always respond with 200 OK
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Step 5: Error Handling

Always implement proper error handling:

try {
  const response = await fetch('https://api.verifyza.com/v1/verify', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.VERIFYZA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(verificationData)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error}`);
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error('Verification failed:', error.message);
  // Handle error appropriately
}

Common Error Codes

Code	Description	Solution
401	Invalid API key	Check your API key is correct and active
400	Invalid request data	Validate your request payload
429	Rate limit exceeded	Implement exponential backoff
500	Server error	Retry the request or contact support

Next Steps

Now that you've made your first verification request, explore these advanced features:

• Batch Verification - Process multiple verifications efficiently
• Transaction Monitoring - Real-time AML compliance
• Passkey Integration - Modern biometric authentication
• Webhook Security - Secure your webhook endpoints

Need Help?

• 📧 Email: support@verifyza.com
• 💬 Live chat on our website
• 📖 Browse our API Reference
• 🔍 Check common issues

---

Congratulations! You've successfully integrated VerifyZA. Ready to explore more advanced features?