Phone Numbers

Search available numbers

Search the provider's inventory for numbers available to purchase in a country (default US). Optional filters narrow the results. The country must be offerable (see GET /v1/phone-numbers/countries). Voice capability is always required; pass sms=true to only see numbers that can also text (SMS support is per-number, not per-country). Numbers a purchase would refuse are left out, and any result's phoneNumber can be bought exactly by passing it to POST /v1/phone-numbers/purchase.

Works without an API key. Keyless calls get up to 12 results with the middle digits masked (maskedNumber), each with a claimId and a claimUrl: a signup link that lands a person on the dashboard's confirm step with that number picked, so an agent can search for a user and hand them one link. Keyless calls are rate limited per IP and results are cached for a few minutes. With an API key you get full numbers and no claim fields.

Billing: Read (free unless it says otherwise) · Rate limit: 120/min

get/v1/messaging/phone-numbers/available

Request

  • Base URL: https://apihub.co.il
  • URL: https://apihub.co.il/v1/messaging/phone-numbers/available
  • Auth: HTTP bearer

Query parameters

smsboolean

true narrows the pool to SMS-capable numbers. Each result still carries its full features list for per-number capability badging.

typestring

Alias of numberType, kept for existing callers

limitinteger
maskedboolean

true returns the keyless shape (masked numbers with claimId and claimUrl) even when you send an API key, e.g. to hand a user a signup link for a number.

prefixstring

Alias of areaCode, kept for existing callers

countrystring

ISO code, or auto on the keyless shape to search the caller's own country (from their IP) near their city, falling back to US.

areaCodestring

Area code or national dialing code the number must start with, e.g. 415 or 91

containsstring

Pattern to match within the number

localitystring

A city name, matched against the numbering plan (accents and common aliases allowed) and searched by that city's area codes; a name no city of the plan matches returns no numbers. areaCode takes a city name too.

numberType'local' | 'mobile' | 'national' | 'toll_free'

Number type; defaults to the country's WhatsApp-safe type (the same name as on purchase, availability and kyc)

Headers

Idempotency-Keystring

Replay-safe: the same execution is returned instead of charging twice

X-Tagstring

Group calls into one job (e.g. one video) — see GET /v1/usage?tag=…

Response

Completed

idstring

Execution id — stable across internal retries; use it with GET /v1/executions/{id}

status'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
operationstring
tagstring nullable

Your X-Tag, if sent

created_atstring date-time
completed_atstring date-time nullable
errorstring nullable

Changes

No recorded changes to this operation across all 2 revisions of this API.