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:
- Request: You send the customer's phone number and your webhook URL.
- Consent: The customer gets a prompt on their phone asking them to approve the request.
- 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​
| Name | Position | Required | Description |
|---|---|---|---|
| token | Headers | True | app secret key |
| msisdn | Body | True | customer phone number |
| webhookUrl | Body | True | The URL where the final KYC details should be sent upon completion. |
{
"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.
{
"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
{
"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.
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.
{
"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
}
}