Skip to main content

KYC Details

KYC Details API

The KYC Details endpoint gets the registered identity information (KYC) linked to an MTN phone number. This includes the subscriber's name, date of birth, gender, and address.

Because this is personal data, the customer has to give consent on their own device before anything is shared. The flow works like this:

  1. Request: You send the customer's phone number and your webhook URL.
  2. Consent: The customer gets a prompt on their phone asking them to approve the request.
  3. Delivery: When the customer approves, CreditChek sends the KYC details to your webhook URL.

Request KYC Details​

Starts the KYC lookup and sends a consent prompt to the customer's MTN line.

POST: https://api.creditchek.africa/v1/telco/v1/ng/mtn/kyc-details

Request Parameters​

NamePositionRequiredDescription
tokenHeadersTrueapp secret key
msisdnBodyTruecustomer phone number
webhookUrlBodyTrueThe URL where the final KYC details should be sent upon completion.
Sample request
{
"msisdn": "2348135429260",
"webhookUrl": "https://your-domain.com/creditchek-callback"
}

Sample Response​

Success response requesting consent from the customer

This first response does not include the KYC details. It confirms that the request was received and the consent prompt was sent to the customer. consentStatus will be PENDING_CONSENT until the customer responds.

Sample Response
{
"status": true,
"data": {
"type": "ASYNC",
"msisdn": "2347062021000",
"transactionId": "rrt-8712907420097953922-c-geu1-1653527-39304482-2",
"consentStatus": "PENDING_CONSENT",
"note": "Result will be sent to your callback url once the customer responds",
"requestTime": "2026-03-02T12:41:07.413Z"
},
"message": "KYC Response fetched successfully",
"error": false
}

Error response when the phone number is not found

Sample Error Response
{
"status": false,
"message": "MSISDN is not found.",
"error": true,
"data": {
"statusCode": "1001",
"statusMessage": "MSISDN is not found.",
"sequenceNo": "20251127150054000263",
"transactionId": "rrt-2529424144842875252-c-geu2-863383-50015461-1"
}
}

Webhook (Async Response)​

Because this endpoint involves prompting the user for consent on their device, the final KYC details are delivered asynchronously.

Once the customer approves the consent request, CreditChek will POST the final KYC details to the Webhook URL you provided in your request body.

Webhook Setup

Make sure your webhookUrl is publicly reachable, accepts POST requests with a JSON body, and replies with a 2xx status code once it gets the payload.

Sample Webhook Payload
{
"event": "telco_kyc_details",
"data": {
"status": true,
"data": {
"type": "SYNC",
"msisdn": "2348135429260",
"transactionId": "rrt-696293431024534450-a-geu2-1273091-51490521-2",
"customerInfo": {
"firstName": "AYOMIDE",
"middleName": "MICHEAL",
"lastName": "SALIHU",
"phoneNumber": "2348145329251",
"city": "MUNICIPAL AREA COUNCIL",
"dateOfBirth": "19730707",
"gender": "m",
"registrationDate": "10/05/2014",
"stateOfOrigin": "FCT",
"streetAddress": "464, LAYOUT, ABUJA"
}
},
"message": "KYC details retrieved successfully",
"error": false
}
}