Phone Validation API

The Phone Validation API validates phone numbers and returns structured metadata about each number. Accept numbers in E.164 format or national format with an optional region code. Responses include validity, formatting, country, line type, carrier, geocoder data, and time zones.

Base URL: https://api.omaxtelecom.com/numbers/

---

What can you do?

Capability	Endpoint	Description
Single validation	POST /phone-validation	Validate one phone number
Bulk validation	POST /phone-validation/bulk	Submit a batch validation job (async)
Job status	GET /phone-validation/bulk/{job_id}	Poll bulk job progress and results
Health	GET /phone-validation/health	Check service availability (no auth)

---

Authentication

All endpoints except /phone-validation/health require OAuth 2.0 Client Credentials via OmaxTelecom ID:

Code
 
Authorization: Bearer <access_token>

Obtain a token from the shared OmaxTelecom API auth endpoint. This is not under the Phone Validation base URL — see the Auth API reference:

Code
 
POST https://api.omaxtelecom.com/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Get your client_id and client_secret from OmaxTelecom Console.

For M2M clients without an organization claim in the token, include:

Code
 
X-Organization-Id: <organization_id>

---

Billing

When price_per_validation is greater than zero for your organisation, each successful validation is charged via the Console Wallet API — including repeat validations for the same number.

HTTP status	Error code	Meaning
402	INSUFFICIENT_BALANCE	Wallet balance too low
403	PHONE_VALIDATION_DISABLED	Phone validation not enabled for your organisation
403	BILLING_NOT_CONFIGURED	Billing is not configured
403	ORGANIZATION_NOT_FOUND	Organisation not registered
422	VALIDATION_ERROR	Invalid request body or phone number format

---

Response envelope

Successful responses:

Code
 
{
  "success": true,
  "data": {
    "valid": true,
    "possible": true,
    "phone_number": "+38766000111",
    "national_format": "066 000-111",
    "country_code": "BA",
    "calling_code": "387",
    "number_type": "MOBILE",
    "geocoder": {
      "description": "Bosnia and Herzegovina",
      "locale": "en"
    },
    "time_zones": ["Europe/Sarajevo"],
    "carrier": {
      "name": "BH Telecom",
      "locale": "en"
    }
  }
}

Error responses:

Code
 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The phone number field format is invalid."
  }
}

Validation result fields

Field	Description
valid	Whether the number is valid for the detected region
possible	Whether the number could be valid with more digits
phone_number	Normalized E.164 phone number
national_format	Nationally formatted number
country_code	ISO 3166-1 alpha-2 country code
calling_code	International calling code
number_type	Line type (e.g. MOBILE, FIXED_LINE)
geocoder	Geographic description for the number
time_zones	Associated time zones
carrier	Carrier name when available

---

Examples

Validate E.164 number

Code
 
curl -X POST "https://api.omaxtelecom.com/numbers/phone-validation" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+38766000111", "locale": "en"}'

Response 200 OK:

Code
 
{
  "success": true,
  "data": {
    "valid": true,
    "possible": true,
    "phone_number": "+38766000111",
    "national_format": "066 000-111",
    "country_code": "BA",
    "calling_code": "387",
    "number_type": "MOBILE",
    "geocoder": {
      "description": "Bosnia and Herzegovina",
      "locale": "en"
    },
    "time_zones": ["Europe/Sarajevo"],
    "carrier": {
      "name": "BH Telecom",
      "locale": "en"
    }
  }
}

Validate national number with region

Code
 
curl -X POST "https://api.omaxtelecom.com/numbers/phone-validation" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "066000111", "region": "BA", "locale": "en"}'

Returns the same normalized result as the E.164 example above.

Bulk validation

Code
 
curl -X POST "https://api.omaxtelecom.com/numbers/phone-validation/bulk" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "en",
    "validations": [
      {"phone_number": "+38766000111"},
      {"phone_number": "066000111", "region": "BA"}
    ]
  }'

Response 202 Accepted:

Code
 
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c"
  }
}

Poll the job:

Code
 
curl "https://api.omaxtelecom.com/numbers/phone-validation/bulk/9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c" \
  -H "Authorization: Bearer <access_token>"

Response 200 OK (processing):

Code
 
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c",
    "status": "processing",
    "total_count": 2,
    "processed_count": 1,
    "failed_count": 0,
    "items": [
      {
        "phone_number": "+38766000111",
        "region": null,
        "locale": "en",
        "status": "completed",
        "result": {
          "valid": true,
          "possible": true,
          "phone_number": "+38766000111",
          "national_format": "066 000-111",
          "country_code": "BA",
          "calling_code": "387",
          "number_type": "MOBILE"
        },
        "error": null
      },
      {
        "phone_number": "066000111",
        "region": "BA",
        "locale": "en",
        "status": "pending",
        "result": null,
        "error": null
      }
    ]
  }
}

Health check

Code
 
curl "https://api.omaxtelecom.com/numbers/phone-validation/health"

Response 200 OK:

Code
 
{
  "ok": true,
  "timestamp": "2026-08-20T16:42:00+00:00"
}

---

Getting started

1. Enable phone validation for your organisation in OmaxTelecom Console.
2. Obtain an access token via OmaxTelecom ID using your client_id and client_secret.
3. Call GET /phone-validation/health to confirm the service is reachable.
4. Validate a single number with POST /phone-validation.
5. Use bulk endpoints when you need to validate large lists asynchronously.

API Documentation

Need Help?

Contact [email protected] for integration support.