The E.164 phone number format is a plus sign, the country code and the national number with its leading 0 removed, with no spaces: for example 0712 345 678 in Kenya becomes +254712345678. Send every to number to the eSMS SMS API this way. The API tidies up spacing and some common mistakes for you, but it never guesses a missing country code, because a wrong guess sends the message to the wrong country.

Last reviewed: 29 October 2026

How to convert numbers to the E.164 phone number format

  1. Find the country code

    Every country has a calling code: +254 Kenya, +256 Uganda, +255 Tanzania, +250 Rwanda, +260 Zambia, +234 Nigeria, +233 Ghana, +237 Cameroon, +27 South Africa. The country pages in the docs list the code and the expected number of digits for each African country.

  2. Drop the leading 0 and add the code

    Remove the trunk prefix 0 that people dial at home, then put + and the country code in front:

    Written locallyE.164
    0712 345 678 (Kenya)+254712345678
    0772 123 456 (Uganda)+256772123456
    0803 123 4567 (Nigeria)+2348031234567
    677 12 34 56 (Cameroon, no trunk 0)+237677123456

    An E.164 number is at most 15 digits after the +.

  3. Know what the API corrects for you

    On single sends and Verify, the API accepts and normalises +254712345678, 254712345678 (no plus), 00254712345678, and numbers with spaces, dashes, dots or brackets. It also removes a stray 0 after the country code, so +2540712345678 is read as +254712345678. What it will not do is add a country code to 0712345678; that is refused with missing_country_code, and the message suggests the international form for your account's country:

    {
  "error": {
    "code": "missing_country_code",
    "message": "'0712345678' has no country code. Send numbers in international (E.164) format: country code + number without the leading 0, e.g. +237677123456. For Kenya that is +254712345678."
  }
}

  4. Use a default country for local lists

    If your data is full of local numbers, tell eSMS which country they belong to instead of converting them by hand. The personalised batch endpoint takes "default_country": "UG" so 0701234567 is read as a Ugandan number. For imports and contacts in the dashboard, set DEFAULT COUNTRY under Settings > Messaging. Numbers that already have a country code always work.

  5. Validate before you send

    POST /api/messages/validate checks up to 1,000 numbers in one call, with no charge and no message sent. It returns the E.164 form, whether the number is valid, its country and its line type, so you can drop landlines and typos first:

    curl -X POST https://sms.esmsafrica.io/api/messages/validate \
  -H "Authorization: Bearer $ESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": ["+256772123456", "0712 345 678", "+2348031234567"]}'

    A single result looks like this (an array request also returns totals and a results list):

    {
  "input": "+256772123456",
  "e164": "+256772123456",
  "valid": true,
  "possible": true,
  "country": "UG",
  "type": "mobile",
  "national": "0772 123456",
  "reason": null
}

    Validation is offline: it checks the format, the country and the number range, not whether the phone is switched on.

Common errors and how to fix them

What you seeWhat it meansHow to fix it
400 missing_country_codeA local number with no country code, such as 0712345678.Add the country code and drop the leading 0, or pass default_country on a batch.
400 invalid_phone_lengthThe number has the wrong number of digits for its country. details includes expected_digits and got_digits.Check for a missing or extra digit; the message includes an example number.
400 invalid_phoneNot a phone number (letters, empty), an unknown country code, or digits outside every network range in that country.Correct the number; run it through the validate endpoint to see why.
A Kenyan number reaches the wrong countryThe number was stored without a country code and converted with the wrong one somewhere in your system.Store E.164 with the country you collected, and never prepend a code blindly.
rejected entries with landline in a batchThe number is a fixed line, which cannot receive SMS.Remove it or ask the customer for a mobile number.

Frequently asked questions

Do I have to include the plus sign?

It is recommended. The API also accepts the same digits without the plus, or with a 00 prefix, and normalises them to E.164.

Why won't the API add my country code automatically?

A local number such as 0712345678 can be valid in more than one country, so a guess could send your message to the wrong network. You state the country, in the number or as default_country on a batch, and the API never guesses.

What about numbers with spaces or dashes?

They are fine. Spaces, dashes, dots and brackets are removed before the number is checked.

Does validation tell me if a phone is on?

No. It checks the format, country and line type offline. Whether the phone received the message comes back in the delivery report.

Do the SDKs format numbers for me?

They pass the number through, and the API applies the rules above. Send E.164 from your code to be safe.

Ready? Create a free eSMS account, then create a test API key and send your first simulated message in minutes. Nothing is charged until you switch to a live key.