OmaxTelecom Developer Portal

Phone Numbers API

The Phone Numbers API lets you search, purchase, and manage phone numbers, configure voice/SMS routing endpoints, send and receive SMS, and submit KYC. All phone numbers must be in E.164 format (for example +447700900001).

View API Documentation →

Interactive reference, request/response schemas, and examples

Use the Interactive Playground on the API reference page to test endpoints with your Console client_id and client_secret. Download the Postman collection and environment from the same page.

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

What can you do?

Capability	Endpoint	Description
Verify context	`GET /me`	Verify token and organization context
Health	`GET /health`	Check service availability (no auth)
Search catalog	`GET /available`	Search available numbers to purchase
Preview cost	`POST /preview`	Get a purchase quote for catalog number IDs
Purchase	`POST /`	Purchase one or more numbers
List owned	`GET /`	List numbers owned by your organisation
Get / release	`GET/DELETE /{phoneNumberId}`	View or release a number
Routing	`GET/PUT /{phoneNumberId}/routing`	Configure voice/SMS routing
Per-number KYC	`GET/POST /{phoneNumberId}/kyc`	View or submit number KYC
Endpoints	`GET/POST /endpoints`	Manage voice/SMS routing endpoints
SMS pricing	`GET /sms/pricing`	Get outbound SMS pricing
Send SMS	`POST /sms/send`	Send outbound SMS from an owned number
Inbound SMS	`GET /sms/messages`	List inbound SMS messages
Partner webhook	`GET/PUT /sms/webhook`	Configure inbound SMS webhook
Org KYC	`GET/POST /kyc/organization`	Organisation-level KYC

Authentication

All endpoints except /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 Numbers 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>

Verify your token and organisation context with GET /me.

Billing

Number purchases, inbound SMS, and outbound SMS may be charged via the Console Wallet API depending on configured sell rates.

HTTP status	Error code	Meaning
`402`	`INSUFFICIENT_BALANCE`	Wallet balance too low
`403`	`PHONE_NUMBERS_DISABLED`	Phone numbers not enabled for your organisation
`403`	`BILLING_NOT_CONFIGURED`	Billing is not configured
`403`	`ORGANIZATION_NOT_FOUND`	Organisation not registered
`403`	`KYC_REQUIRED`	Organisation KYC approval required before purchasing
`403`	`TRAFFIC_RESTRICTED`	Outbound SMS not permitted
`404`	`OFFERING_NOT_FOUND`	No offering found for the requested country/type
`422`	`VALIDATION_ERROR`	Invalid request body or phone number format
`502`	`OUTBOUND_SMS_FAILED`	Outbound SMS failed at supplier

Response envelope

Successful responses:


Code
{
  "success": true,
  "data": { ... }
}

Error responses:


Code
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Purchase workflow

Search — GET /available returns catalog number IDs (opaque UUIDs with a short TTL)
Preview — POST /preview returns a cost quote and optional quote_token
Purchase — POST / using the catalog number ID(s) from step 1 or 2

Examples

Search available numbers

Code
curl "https://api.omaxtelecom.com/numbers/available?country_iso=GB&number_type=mobile&limit=20" \
  -H "Authorization: Bearer <access_token>"

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "e164": "+447700900123",
        "phone_number": "+447700900123",
        "national_format": "07700 900123",
        "country_iso": "GB",
        "number_type": "mobile",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "billing_period": "monthly",
        "currency": "EUR",
        "value_tier": "standard"
      }
    ],
    "total_available": 42
  }
}

Preview purchase cost

Code
curl -X POST "https://api.omaxtelecom.com/numbers/preview" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"number_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]}'

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "e164": "+447700900123",
        "phone_number": "+447700900123",
        "national_format": "07700 900123",
        "country_iso": "GB",
        "number_type": "mobile",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "billing_period": "monthly",
        "currency": "EUR",
        "value_tier": "standard"
      }
    ],
    "quote": {
      "connection_cost": 5,
      "monthly_cost": 2,
      "total_cost": 7,
      "currency": "EUR",
      "quote_token": "qt_abc123xyz",
      "expected_total_cost_minor": 700,
      "first_billing_date": "2026-09-17",
      "next_billing_date": "2026-10-17"
    }
  }
}

Purchase a number

Code
curl -X POST "https://api.omaxtelecom.com/numbers" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: purchase-2026-09-17-001" \
  -d '{"number_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}'

Response 201 Created:


Code
{
  "success": true,
  "data": {
    "order_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "phone_numbers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "e164": "+447700900001",
        "phone_number": "+447700900001",
        "national_format": "07700 900001",
        "country_iso": "GB",
        "number_type": "local",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "status": "provisioning",
        "kyc_status": "approved",
        "traffic_direction": "inbound_and_outbound",
        "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "next_billing_date": "2026-10-01",
        "billing_period": "monthly",
        "currency": "EUR"
      }
    ]
  }
}

List owned numbers

Code
curl "https://api.omaxtelecom.com/numbers?page=1&per_page=20" \
  -H "Authorization: Bearer <access_token>"

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "phone_numbers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "e164": "+447700900001",
        "phone_number": "+447700900001",
        "national_format": "07700 900001",
        "country_iso": "GB",
        "number_type": "local",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "status": "active",
        "kyc_status": "approved",
        "traffic_direction": "inbound_and_outbound",
        "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "next_billing_date": "2026-10-01",
        "billing_period": "monthly",
        "currency": "EUR"
      }
    ],
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}

Send outbound SMS

Code
curl -X POST "https://api.omaxtelecom.com/numbers/sms/send" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+447700900001",
    "to": "+447911123456",
    "body": "Your verification code is 123456"
  }'

Response 201 Created:


Code
{
  "success": true,
  "data": {
    "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "+447700900001",
    "to": "+447911123456",
    "body": "Your verification code is 123456",
    "segments": 1,
    "status": "sent",
    "sent_at": "2026-09-17T09:20:00+00:00",
    "delivered_at": null
  }
}

Configure inbound SMS webhook

Code
curl -X PUT "https://api.omaxtelecom.com/numbers/sms/webhook" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/inbound-sms",
    "secret": "my-webhook-secret-16chars",
    "enabled": true
  }'

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "url": "https://api.example.com/webhooks/inbound-sms",
    "enabled": true,
    "has_secret": true
  }
}

Health check

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

Response 200 OK:


Code
{
  "ok": true,
  "timestamp": "2026-09-17T12:00:00+00:00"
}

Getting started

Enable phone numbers for your organisation in OmaxTelecom Console.
Obtain an access token via OmaxTelecom ID using your client_id and client_secret.
Call GET /health to confirm the service is reachable.
Verify context with GET /me.
Search available numbers with GET /available, preview cost, then purchase.
Configure routing endpoints and inbound SMS webhook as needed.

API Documentation

Complete API Reference

Explore all endpoints with interactive examples, schemas, authentication details, and Postman downloads.

View API Documentation →

Need Help?

Contact [email protected] for integration support.

Last modified on September 17, 2026

Phone Numbers API

View API Documentation →

Interactive reference, request/response schemas, and examples

Use the Interactive Playground on the API reference page to test endpoints with your Console client_id and client_secret. Download the Postman collection and environment from the same page.

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

What can you do?

Capability	Endpoint	Description
Verify context	`GET /me`	Verify token and organization context
Health	`GET /health`	Check service availability (no auth)
Search catalog	`GET /available`	Search available numbers to purchase
Preview cost	`POST /preview`	Get a purchase quote for catalog number IDs
Purchase	`POST /`	Purchase one or more numbers
List owned	`GET /`	List numbers owned by your organisation
Get / release	`GET/DELETE /{phoneNumberId}`	View or release a number
Routing	`GET/PUT /{phoneNumberId}/routing`	Configure voice/SMS routing
Per-number KYC	`GET/POST /{phoneNumberId}/kyc`	View or submit number KYC
Endpoints	`GET/POST /endpoints`	Manage voice/SMS routing endpoints
SMS pricing	`GET /sms/pricing`	Get outbound SMS pricing
Send SMS	`POST /sms/send`	Send outbound SMS from an owned number
Inbound SMS	`GET /sms/messages`	List inbound SMS messages
Partner webhook	`GET/PUT /sms/webhook`	Configure inbound SMS webhook
Org KYC	`GET/POST /kyc/organization`	Organisation-level KYC

Authentication

All endpoints except /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 Numbers 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>

Verify your token and organisation context with GET /me.

Billing

Number purchases, inbound SMS, and outbound SMS may be charged via the Console Wallet API depending on configured sell rates.

HTTP status	Error code	Meaning
`402`	`INSUFFICIENT_BALANCE`	Wallet balance too low
`403`	`PHONE_NUMBERS_DISABLED`	Phone numbers not enabled for your organisation
`403`	`BILLING_NOT_CONFIGURED`	Billing is not configured
`403`	`ORGANIZATION_NOT_FOUND`	Organisation not registered
`403`	`KYC_REQUIRED`	Organisation KYC approval required before purchasing
`403`	`TRAFFIC_RESTRICTED`	Outbound SMS not permitted
`404`	`OFFERING_NOT_FOUND`	No offering found for the requested country/type
`422`	`VALIDATION_ERROR`	Invalid request body or phone number format
`502`	`OUTBOUND_SMS_FAILED`	Outbound SMS failed at supplier

Response envelope

Successful responses:


Code
{
  "success": true,
  "data": { ... }
}

Error responses:


Code
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Purchase workflow

Search — GET /available returns catalog number IDs (opaque UUIDs with a short TTL)
Preview — POST /preview returns a cost quote and optional quote_token
Purchase — POST / using the catalog number ID(s) from step 1 or 2

Examples

Search available numbers

Code
curl "https://api.omaxtelecom.com/numbers/available?country_iso=GB&number_type=mobile&limit=20" \
  -H "Authorization: Bearer <access_token>"

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "e164": "+447700900123",
        "phone_number": "+447700900123",
        "national_format": "07700 900123",
        "country_iso": "GB",
        "number_type": "mobile",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "billing_period": "monthly",
        "currency": "EUR",
        "value_tier": "standard"
      }
    ],
    "total_available": 42
  }
}

Preview purchase cost

Code
curl -X POST "https://api.omaxtelecom.com/numbers/preview" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"number_ids": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]}'

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "e164": "+447700900123",
        "phone_number": "+447700900123",
        "national_format": "07700 900123",
        "country_iso": "GB",
        "number_type": "mobile",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "billing_period": "monthly",
        "currency": "EUR",
        "value_tier": "standard"
      }
    ],
    "quote": {
      "connection_cost": 5,
      "monthly_cost": 2,
      "total_cost": 7,
      "currency": "EUR",
      "quote_token": "qt_abc123xyz",
      "expected_total_cost_minor": 700,
      "first_billing_date": "2026-09-17",
      "next_billing_date": "2026-10-17"
    }
  }
}

Purchase a number

Code
curl -X POST "https://api.omaxtelecom.com/numbers" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: purchase-2026-09-17-001" \
  -d '{"number_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"}'

Response 201 Created:


Code
{
  "success": true,
  "data": {
    "order_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "phone_numbers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "e164": "+447700900001",
        "phone_number": "+447700900001",
        "national_format": "07700 900001",
        "country_iso": "GB",
        "number_type": "local",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "status": "provisioning",
        "kyc_status": "approved",
        "traffic_direction": "inbound_and_outbound",
        "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "next_billing_date": "2026-10-01",
        "billing_period": "monthly",
        "currency": "EUR"
      }
    ]
  }
}

List owned numbers

Code
curl "https://api.omaxtelecom.com/numbers?page=1&per_page=20" \
  -H "Authorization: Bearer <access_token>"

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "phone_numbers": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "e164": "+447700900001",
        "phone_number": "+447700900001",
        "national_format": "07700 900001",
        "country_iso": "GB",
        "number_type": "local",
        "connection_fee": "5.000000",
        "monthly_fee": "2.000000",
        "total_fee": "7.000000",
        "status": "active",
        "kyc_status": "approved",
        "traffic_direction": "inbound_and_outbound",
        "voice_endpoint_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "sms_endpoint_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "next_billing_date": "2026-10-01",
        "billing_period": "monthly",
        "currency": "EUR"
      }
    ],
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}

Send outbound SMS

Code
curl -X POST "https://api.omaxtelecom.com/numbers/sms/send" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+447700900001",
    "to": "+447911123456",
    "body": "Your verification code is 123456"
  }'

Response 201 Created:


Code
{
  "success": true,
  "data": {
    "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "phone_number_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from": "+447700900001",
    "to": "+447911123456",
    "body": "Your verification code is 123456",
    "segments": 1,
    "status": "sent",
    "sent_at": "2026-09-17T09:20:00+00:00",
    "delivered_at": null
  }
}

Configure inbound SMS webhook

Code
curl -X PUT "https://api.omaxtelecom.com/numbers/sms/webhook" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/inbound-sms",
    "secret": "my-webhook-secret-16chars",
    "enabled": true
  }'

Response 200 OK:


Code
{
  "success": true,
  "data": {
    "url": "https://api.example.com/webhooks/inbound-sms",
    "enabled": true,
    "has_secret": true
  }
}

Health check

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

Response 200 OK:


Code
{
  "ok": true,
  "timestamp": "2026-09-17T12:00:00+00:00"
}

Getting started

Enable phone numbers for your organisation in OmaxTelecom Console.
Obtain an access token via OmaxTelecom ID using your client_id and client_secret.
Call GET /health to confirm the service is reachable.
Verify context with GET /me.
Search available numbers with GET /available, preview cost, then purchase.
Configure routing endpoints and inbound SMS webhook as needed.

API Documentation

Complete API Reference

Explore all endpoints with interactive examples, schemas, authentication details, and Postman downloads.

View API Documentation →

Need Help?

Contact [email protected] for integration support.

Last modified on September 17, 2026