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.

[!TIP] Test the API Instantly: Fork our Melon Developer API Postman Collection to start sending test requests immediately.

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"
    }
  ],
  "relogReason": "Optional reason if recreating a previously existing record"
}

[!NOTE] Duplicate Handling Melon API checks for duplicates using phone, email, and loanId (first and last names are not considered unique). If a duplicate is found in the current environment, the API returns a 400 Bad Request.

• If you simply need to update an existing customer, use PUT /api/v1/customers/:id.
• If you intentionally need to re-log a customer (e.g. they applied again for a new loan), include the relogReason string in your request body to bypass the duplicate check.

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

Add Address

Append a new address to an existing customer for verification (Max 5 addresses per customer).

POST /api/v1/customers/:id/addresses

Required Scope: kyc:write

Request Body Example

{
  "label": "Office Address",
  "streetNumber": "19",
  "streetName": "Adeola Hopewell",
  "city": "Victoria Island",
  "state": "Lagos",
  "country": "Nigeria"
}

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

{
  "status": true,
  "message": "Verification status retrieved",
  "data": {
    "customerId": "cust_1234567890",
    "customerName": "Babatunde Ogunlesi",
    "overallStatus": "VERIFIED",
    "verificationDate": "2024-06-10T14:30:00.000Z",
    "addresses": [
      {
        "label": "Home Address",
        "status": "VERIFIED",
        "city": "Victoria Island",
        "state": "Lagos",
        "verificationData": {
          "verifiedAddress": "15 Adeola Hopewell, Victoria Island, Lagos",
          "verifiedAt": "2024-06-10T14:25:00.000Z",
          "agentNotes": "Address confirmed. Resident provided ID."
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_123abc456def",
    "timestamp": "2024-06-10T14:30:00.000Z"
  }
}

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

{
  "status": true,
  "message": "Verification statistics retrieved",
  "data": {
    "total": 1500,
    "pending": 200,
    "verified": 1250,
    "rejected": 50
  },
  "meta": {
    "requestId": "req_123abc456def",
    "timestamp": "2024-06-10T14:30:00.000Z"
  }
}