Number Lookup API

The Number Lookup API performs carrier lookups for phone numbers in E.164 format. Responses include carrier name, line type, and MCC/MNC codes. Version 1 supports carrier lookup only.

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

---

What can you do?

Capability	Endpoint	Description
Single lookup	POST /number-lookup	Carrier lookup for one E.164 number
Bulk lookup	POST /number-lookup/bulk	Submit a batch lookup job (async)
Job status	GET /number-lookup/bulk/{job_id}	Poll bulk job progress and results
Health	GET /number-lookup/health	Check service availability (no auth)

---

Authentication

All endpoints except /number-lookup/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 Number Lookup 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_lookup is greater than zero for your organisation, each lookup is charged via the Console Wallet API — including repeat lookups for the same number.

HTTP status	Error code	Meaning
402	INSUFFICIENT_BALANCE	Wallet balance too low
403	NUMBER_LOOKUP_DISABLED	Number lookup not enabled for your organisation
403	BILLING_NOT_CONFIGURED	Billing is not configured
403	ORGANIZATION_NOT_FOUND	Organisation not registered
422	—	Invalid E.164 format or request validation error
503	NUMBER_LOOKUP_UNAVAILABLE	Lookup provider unavailable

---

Phone number format

All phone numbers must be in E.164 format, for example +38766000111.

---

Response envelope

Successful responses:

Code
 
{
  "success": true,
  "data": {
    "phone_number": "+38766000111",
    "country_code": "BA",
    "national_format": "066 000-111",
    "valid": true,
    "carrier": {
      "name": "BH Telecom",
      "type": "mobile",
      "mcc": "218",
      "mnc": "90"
    }
  }
}

Error responses:

Code
 
{
  "success": false,
  "error": {
    "code": "NUMBER_LOOKUP_UNAVAILABLE",
    "message": "Number lookup service unavailable"
  }
}

Lookup result fields

Field	Description
phone_number	Normalized E.164 phone number
country_code	ISO 3166-1 alpha-2 country code
national_format	Nationally formatted number
valid	Whether the number is considered valid
carrier.name	Carrier name when available
carrier.type	Line type (e.g. mobile, landline)
carrier.mcc	Mobile Country Code
carrier.mnc	Mobile Network Code

---

Examples

Single carrier lookup

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

Response 200 OK:

Code
 
{
  "success": true,
  "data": {
    "phone_number": "+38766000111",
    "country_code": "BA",
    "national_format": "066 000-111",
    "valid": true,
    "carrier": {
      "name": "BH Telecom",
      "type": "mobile",
      "mcc": "218",
      "mnc": "90"
    }
  }
}

Invalid number (still returns 200)

When a number is found but marked invalid, the API returns 200 OK with valid: false:

Code
 
{
  "success": true,
  "data": {
    "phone_number": "+15551234567",
    "country_code": "US",
    "national_format": "(555) 123-4567",
    "valid": false
  }
}

Bulk lookup

Code
 
curl -X POST "https://api.omaxtelecom.com/numbers/number-lookup/bulk" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": [
      "+38766000111",
      "+38761111222"
    ]
  }'

Response 202 Accepted:

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

Poll the job (recommended interval: 1–3 seconds):

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

Response 200 OK (completed):

Code
 
{
  "success": true,
  "data": {
    "job_id": "9f3c2b1a-7d6e-4f5a-8b9c-0d1e2f3a4b5c",
    "status": "completed",
    "total_count": 2,
    "processed_count": 2,
    "failed_count": 0,
    "items": [
      {
        "phone_number": "+38766000111",
        "status": "completed",
        "result": {
          "phone_number": "+38766000111",
          "country_code": "BA",
          "national_format": "066 000-111",
          "valid": true,
          "carrier": {
            "name": "BH Telecom",
            "type": "mobile",
            "mcc": "218",
            "mnc": "90"
          }
        },
        "error": null
      },
      {
        "phone_number": "+38761111222",
        "status": "completed",
        "result": {
          "phone_number": "+38761111222",
          "country_code": "BA",
          "national_format": "061 111-222",
          "valid": true,
          "carrier": {
            "name": "HT Eronet",
            "type": "mobile",
            "mcc": "218",
            "mnc": "03"
          }
        },
        "error": null
      }
    ]
  }
}

Maximum 1000 unique phone numbers per bulk request.

Health check

Code
 
curl "https://api.omaxtelecom.com/numbers/number-lookup/health"

Response 200 OK:

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

---

Getting started

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

API Documentation

Need Help?

Contact [email protected] for integration support.