Numbers API Overview

The Numbers API lets you programmatically search for and purchase phone numbers. You start broad (pick a country) and narrow down to a specific number.

The purchase flow

Pick a location → Search for numbers → Check requirements → Purchase

Most integrations follow exactly this flow. The steps below explain each stage.

Step 1: Find a location

The only required parameter to search for numbers is a country code. You can optionally narrow down by region or city:

1. Get Regions — available for US, CA, and GB. Required for US (too many area codes to search without one). Each region has an id.
2. Get Cities — pass a country and optionally a region ID to get cities. Each city has an id.

Step 2: Search for numbers

Search Number Groups is the main search endpoint. Pass a country (required) plus optional filters like region_id, city_id, city_name_or_prefix, and did_type. See the full parameter reference for details.

Each group in the response includes pricing, features (voice, SMS, WhatsApp), and a group_id.

You can filter by number type using DID Types — local, mobile, tollfree, national, global, or sharedcost.

If a group has allow_number_selection: true, use Available Numbers with the group_id to browse individual phone numbers or search for vanity numbers with number_contains.

Check requirements before purchasing

Some countries require identity documents or proof of address. Use Get Requirements to check what's needed before you buy. Groups also include a requirements array — if it's empty, no documents are needed.

Purchasing a number without meeting the requirements can result in the number being suspended.

Step 3: Purchase

Purchase Numbers — POST with a group_id and optionally a specific number to buy it directly.

Optional: Reserve before purchasing

If you need to hold a number before committing (e.g., to show it to a user before charging), you can reserve it first:

1. Reserve a Number — POST with a group_id and optionally a specific number. Returns a reservation with an expiration time.
2. Purchase Numbers — POST to buy the reserved number before it expires.

You can List Reservations to see active reservations and Cancel a Reservation if you change your mind.

caution

Reservations expire. Always purchase before the expires_at time on the reservation.

Quick example: Buy a local number in Los Angeles

# 1. Find the California region
curl 'https://api.p.2chat.io/open/numbers/regions?country=US' \
  -H 'X-User-API-Key: YOUR_KEY'
# → returns region_id: 123 for "California"

# 2. Find Los Angeles
curl 'https://api.p.2chat.io/open/numbers/cities?country=US&region=123' \
  -H 'X-User-API-Key: YOUR_KEY'
# → returns city_id: 456 for "Los Angeles"

# 3. Search for local number groups in LA
curl 'https://api.p.2chat.io/open/numbers/groups?country=US&city_id=456&did_type=local' \
  -H 'X-User-API-Key: YOUR_KEY'
# → returns group_id: "abc-123" with pricing and features

# 4. Browse available numbers in that group
curl 'https://api.p.2chat.io/open/numbers/available?group_id=abc-123' \
  -H 'X-User-API-Key: YOUR_KEY'
# → returns specific numbers like +12135551234

# 5. Purchase the number
curl -X POST 'https://api.p.2chat.io/open/numbers/purchase' \
  -H 'X-User-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"group_id": "abc-123", "number": "+12135551234"}'

All endpoints at a glance

Endpoint	Method	Purpose
/open/numbers/regions	GET	List regions for a country
/open/numbers/cities	GET	List cities, optionally filtered by region
/open/numbers/did-types	GET	List available number types
/open/numbers/requirements	GET	Check regulatory requirements
/open/numbers/groups	GET	Search number groups (main search)
/open/numbers/available	GET	List specific numbers in a group
/open/numbers/reservations	POST	Reserve a number (optional)
/open/numbers/reservations	GET	List active reservations
/open/numbers/reservations/{uuid}	DELETE	Cancel a reservation
/open/numbers/purchase	POST	Purchase numbers