Search available numbers

Search US local numbers you can buy. Read-only — nothing is reserved or charged. Numbers already on the platform are left out.

GET https://api.centerfy.ai/webhooks/inbound/phone-numbers/available

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or use Authorization: Bearer `<key>`.

Query parameters

Name	Type	Required	Default	Description
`country`	`string`	No	`US`	Only US is supported.
`area_code`	`string`	No	—	Area code, 1–3 digits, e.g. 415.
`contains`	`string`	No	—	Digits the number must contain, 1–10 digits.
`type`	`string`	No	`local`	local or toll_free. Toll-free numbers are not sold (400).
`limit`	`integer`	No	`20`	Maximum results; 1–100.

Example

curl -X GET "https://api.centerfy.ai/webhooks/inbound/phone-numbers/available?country=US&type=local&limit=20" \
  -H "x-api-key: $CENTERFY_API_KEY"

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.phoneProvisioning.search({
  "country": "US",
  "type": "local",
  "limit": 20
});
console.log(result);

centerfy phoneProvisioning search '{"country":"US","type":"local","limit":20}'

MCP tool: centerfy_phone_numbers_search_available (see MCP server)

Response

{
  "status": "success",
  "count": 2,
  "available_numbers": [
    {
      "phone_number": "+14155550123",
      "type": "local",
      "locality": "San Francisco",
      "region": "CA",
      "features": [
        "sms",
        "voice"
      ]
    },
    {
      "phone_number": "+14155550188",
      "type": "local",
      "locality": "San Francisco",
      "region": "CA",
      "features": [
        "voice"
      ]
    }
  ]
}

Errors

400 — if type is toll_free or a parameter is malformed.
502 — if the search failed; 503 if number search is not available.

Notes

Availability can change at any moment — a number listed here may be gone when you buy it.