KYC API Reference

The KYC API allows you to programmatically create verification requests, track their statuses, and retrieve finalized reports.

All requests require the Authorization header with a valid API key.

Customers API

Manage the lifecycle of customer KYC records.

Create a Customer

Create a new customer profile and initiate the KYC field verification process.

POST /api/v1/customers

Required Scope: kyc:write

Request Body

{
  "firstName": "Babatunde",
  "lastName": "Ogunlesi",
  "phone": "+2348012345678",
  "email": "babatunde@example.com",
  "bvn": "12345678901",
  "nin": "98765432101",
  "addresses": [
    {
      "label": "Home Address",
      "streetNumber": "15",
      "streetName": "Adeola Hopewell",
      "city": "Victoria Island",
      "state": "Lagos",
      "country": "Nigeria"
    }
  ]
}

List Customers

Retrieve a paginated list of your customers.

GET /api/v1/customers

Required Scope: kyc:read

Query Parameters

• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 20)
• status (optional): Filter by verification status (e.g., PENDING, VERIFIED, REJECTED)
• search (optional): Search by name, email, or phone.

Get Customer Details

Retrieve the full details of a specific customer, including address details and verification status.

GET /api/v1/customers/:id

Required Scope: kyc:read

Update Customer

Modify an existing customer's details.

PUT /api/v1/customers/:id

Required Scope: kyc:write

Delete Customer

Soft-delete a customer record from the active verification queue.

DELETE /api/v1/customers/:id

Required Scope: kyc:write

Download KYC Report

Download a verified customer's final KYC report as a formatted PDF document.

GET /api/v1/customers/:id/report

Required Scope: kyc:read

Verification API

Check and track the verification progress of your customers without fetching full customer profiles.

Get Verification Status

Check the current verification status for a specific customer. This includes the overall status, as well as the individual verification statuses of all provided physical addresses.

GET /api/v1/verification/:customerId/status

Required Scope: kyc:read

Response Example

{
  "success": true,
  "data": {
    "status": "VERIFIED",
    "verifiedAt": "2024-06-10T14:30:00Z",
    "addresses": [
      {
        "label": "Home Address",
        "status": "VERIFIED",
        "agentNotes": "Address confirmed. Resident provided ID."
      }
    ]
  }
}

Get Verification Statistics

Get aggregate verification statistics for your organization. Useful for dashboard integrations.

GET /api/v1/verification/stats

Required Scope: kyc:read

Response Example

{
  "success": true,
  "data": {
    "total": 1500,
    "pending": 200,
    "verified": 1250,
    "rejected": 50
  }
}