KYC Check

Resolves the first name a customer mobile number is registered under with Telebirr, so you can show it to the sender and confirm the recipient before an airtime topup, package topup, or gift voucher purchase.

This is a name lookup and nothing more. It does not report whether a number is active, suspended, or barred, and it does not say why a name is unavailable.

Endpoint

> POST ${BASE_URL}/kyc/check

Payloads

NAME	Type	Description	Required
msisdn	string	Ethio Telecom mobile number of the customer. Accepted formats: 251911234567, +251911234567, 0911234567, 911234567	Yes

Sample Request

Curl

$  curl -H 'Content-Type: application/json' \
        -H 'x-api-token: ACCESS_TOKEN' \
        -d '{ "msisdn": "251911234567" }' \
        "BASE_URL/kyc/check"

Typescript

import * as axios from "axios";

const data = {
  msisdn: "251911234567",
};

axios
  .post("BASE_URL/kyc/check", data, {
    headers: {
      "Content-Type": "application/json",
      "x-api-token": "ACCESS_TOKEN"
    },
  })
  .then((response) => {
    console.log("Success:", response.data);
  })
  .catch((error) => {
    console.error(
      "Error:",
      error.response ? error.response.data : error.message,
    );
  });

Response Schema

Success Schema

{
  success: boolean;
  message: string;
  statusCode: number;
  data: {
    firstName: string | null;
  }
}

Error Schema

{
  statusCode: number;
  success: boolean;
  message: string;
  data: any;
}

• firstName (string | null): First name registered with Telebirr for the number. null when Telebirr returns no name for the number.

Interpreting the result

firstName	Meaning
A name	Telebirr holds a customer record for the number. Show the name to the sender to confirm the recipient.
null	Telebirr returned no name for the number. There is nothing to show the sender.

A number with no name is a successful lookup: you receive 200 with firstName: null, not an error. Do not treat a returned name as confirmation that the number is in service.

Response Codes

Code	Meaning
200	Lookup completed. firstName carries the result and is null when no name is available.
400	msisdn is missing or is not a valid Ethio Telecom number.
401	Missing or invalid x-api-token.
422	The KYC provider rejected the number as not a valid Ethiopian mobile number.
502	The KYC provider is unavailable or could not process the request. Retry after a short delay.
503	KYC lookup is not configured on this environment. Contact support.

Sample Response

{
  "success": true,
  "message": "Successful",
  "statusCode": 200,
  "data": {
    "firstName": "Abebe"
  }
}

Sample Response (no name available)

{
  "success": true,
  "message": "Successful",
  "statusCode": 200,
  "data": {
    "firstName": null
  }
}

Sample Error Response

{
  "success": false,
  "message": "KYC provider is temporarily unavailable. Please try again later.",
  "statusCode": 502,
  "data": null
}

Personal data

firstName is personal data. Use it only to confirm the recipient with the sender before the transaction. Do not persist it or display it beyond that purpose.