Validate numbers

POST /api/messages/validate - Check numbers are valid and mobile before sending.

Endpoint

POST https://sms.esmsafrica.io/api/messages/validate

Also available as POST /api/validate. Offline validation (no charge, no network/HLR call): confirms a number is well-formed and reachable-looking, and names the assigned carrier + region, so you can drop invalid or non-mobile numbers before you spend on them.

Authentication

Authorization: Bearer esms_live_your_api_key

Request body

{ "phone": "+256772123456" }

Pass a single string, or an array of up to 1000 numbers.

Field	Type	Required	Description
`phone`	string or array	Yes	Number(s) in international format (must include the country code).

Response

Single number

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

Field	Description
`valid`	Passes full validation (correct length + range for its country).
`possible`	Loosely plausible even if not fully valid.
`type`	`mobile`, `fixed_line`, `fixed_line_or_mobile`, `voip`, ... - reject non-mobile if you only send to handsets.
`carrier` / `location`	Assigned network and region (offline; not live ported status).
`reason`	Why it failed: `not_numeric`, `parse_error`, `invalid_number`, `impossible_number`.

Array

{
  "count": 3,
  "valid": 2,
  "invalid": 1,
  "mobile": 2,
  "results": [ { "input": "+256772123456", "valid": true, "...": "..." } ]
}

Example

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

Validation is offline (libphonenumber): it verifies format, country and the originally-assigned carrier. It does not perform a live HLR lookup, so it cannot report real-time ported or switched-off status.