BrightshoalDocsOpen console
MenuPhone numbers

API reference

Phone numbers

Search, buy or import numbers, then attach an assistant so it answers inbound calls on that number.

List phone numbers

GET/api/phone-numbers

Numbers in scope, with the assistant each one is attached to and how it routes calls.

Secret API key. How it works

Query parameters

  • project_idstring

    Only this project's numbers.

Returns

200 OK

Response attributes
  • dataarray of PhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/phone-numbers
curl "https://api.brightshoal.com/api/phone-numbers" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": [
    {
      "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "e164": "+14155550123",
      "provider": "string",
      "forward_to": "string",
      "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "status": "active",
      "capabilities": {},
      "routing_mode": "trunk",
      "mode": "live",
      "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
      "provider_metadata": {},
      "created_at": "2026-10-28T09:30:00.000Z",
      "updated_at": "2026-10-28T09:30:00.000Z"
    }
  ]
}

Import a phone number you own

POST/api/phone-numbers

Registers a customer-owned number with provider: null (the default) and forward_to, an active platform number in the same project. The customer configures forwarding with their carrier; attach the assistant to the platform line. For a carrier-managed number, pass an explicit provider and its carrier identifiers, or use the claim endpoint.

Secret API key, not a viewer key. How it works

Request body

  • project_idstring

    Required only for an org-wide key.

  • e164stringrequired

    The number in E.164 format, e.g. +14155550123.

  • providerstring | nullnot empty

    Carrier slug for a managed number. Null or omitted for a customer-owned forwarding number.

  • forward_tostring

    Required for customer-owned numbers. An active platform number in the same project.

  • provider_metadataobject

    Carrier identifiers, for example {"twilioNumberSid":"PN..."} for a Twilio number.

Returns

201 OK

Response attributes
  • dataPhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
POST /api/phone-numbers
curl -X POST "https://api.brightshoal.com/api/phone-numbers" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "e164": "+14155550123"
}'
Response 201
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "e164": "+14155550123",
    "provider": "string",
    "forward_to": "string",
    "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "active",
    "capabilities": {},
    "routing_mode": "trunk",
    "mode": "live",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "provider_metadata": {},
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Get a phone number

GET/api/phone-numbers/{id}

One number with its assistant, routing mode and status.

Secret API key. How it works

Path parameters

  • idstringrequired

    Phone number id, pn_....

Returns

200 OK

Response attributes
  • dataPhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
GET /api/phone-numbers/{id}
curl "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "e164": "+14155550123",
    "provider": "string",
    "forward_to": "string",
    "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "active",
    "capabilities": {},
    "routing_mode": "trunk",
    "mode": "live",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "provider_metadata": {},
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Set a phone number's sandbox mode

PATCH/api/phone-numbers/{id}

Every call to or from a sandbox number is a sandbox call: it runs the assistant's saved draft, reaches sandbox webhooks only and stays out of analytics. A live outbound call cannot use a sandbox number as its caller ID. A database change only; carrier routing (routing_mode) is unchanged. Admins only.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Phone number id, pn_....

Request body

  • modestringrequired

    One of live test

Returns

200 OK

Response attributes
  • dataPhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
PATCH /api/phone-numbers/{id}
curl -X PATCH "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "live"
}'
Response 200
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "e164": "+14155550123",
    "provider": "string",
    "forward_to": "string",
    "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "active",
    "capabilities": {},
    "routing_mode": "trunk",
    "mode": "live",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "provider_metadata": {},
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Release a phone number

DELETE/api/phone-numbers/{id}

Deletes the number from the registry and, when it is carrier-managed and this deployment can reach the carrier, releases it back to the carrier (you lose the number and stop paying for it). Check data.released: false means the carrier was not asked, so the number may still be yours and billed there. Detach its assistant first: an attached number is 409 {"error":"number_attached"}.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Phone number id, pn_....

Returns

200 OK

Response attributes
  • dataPhoneNumberReleaserequired

    3 attributes
    • idstringrequired

    • deletedbooleanrequired

    • releasedbooleanrequired

      Whether the carrier released the number. False when it was not carrier-managed or the deployment has no carrier connection; the registry row is deleted either way.

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 number_attached: detach the assistant first. number_has_forwarding_lines: customer lines forward to this number; remove them first.
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
DELETE /api/phone-numbers/{id}
curl -X DELETE "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "deleted": true,
    "released": true
  }
}

Attach an assistant to a phone number

POST/api/phone-numbers/{id}/attach

Puts an assistant on the number and configures the carrier so inbound calls reach it. The assistant and number must be in the same project, and the assistant not archived (409 assistant_archived; a number already attached to an assistant that is later archived keeps it). routing_mode picks the path: trunk (SIP straight to the voice runtime, cold transfers) or pv_webhook (Twilio Programmable Voice bridge, warm transfers).

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Phone number id, pn_....

Request body

  • assistant_idstringrequirednot empty

  • routing_modestringrequired

    One of trunk pv_webhook

Returns

200 OK

Response attributes
  • dataPhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 409 assistant_archived: the assistant is archived; restore it first
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 503 telephony_not_configured: this deployment has no carrier account
POST /api/phone-numbers/{id}/attach
curl -X POST "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID/attach" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "assistant_id": "asst_7d2e9b14c6a04f3e8b5d1a9c0e7f6b23",
  "routing_mode": "pv_webhook"
}'
Response 200
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "e164": "+14155550123",
    "provider": "string",
    "forward_to": "string",
    "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "active",
    "capabilities": {},
    "routing_mode": "trunk",
    "mode": "live",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "provider_metadata": {},
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Detach the assistant from a phone number

DELETE/api/phone-numbers/{id}/attach

The number stops reaching any assistant. It stays registered and owned; release it to give it up.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Phone number id, pn_....

Returns

200 OK

Response attributes
  • dataPhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
DELETE /api/phone-numbers/{id}/attach
curl -X DELETE "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID/attach" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "e164": "+14155550123",
    "provider": "string",
    "forward_to": "string",
    "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "active",
    "capabilities": {},
    "routing_mode": "trunk",
    "mode": "live",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "provider_metadata": {},
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Change a phone number's routing mode

POST/api/phone-numbers/{id}/mode

Moves an attached number between trunk and pv_webhook routing and reconfigures the carrier, keeping its assistant.

Secret API key, not a viewer key. How it works

Path parameters

  • idstringrequired

    Phone number id, pn_....

Request body

  • routing_modestringrequired

    One of trunk pv_webhook

Returns

200 OK

Response attributes
  • dataPhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 503 telephony_not_configured: this deployment has no carrier account
POST /api/phone-numbers/{id}/mode
curl -X POST "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID/mode" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "routing_mode": "trunk"
}'
Response 200
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "e164": "+14155550123",
    "provider": "string",
    "forward_to": "string",
    "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "active",
    "capabilities": {},
    "routing_mode": "trunk",
    "mode": "live",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "provider_metadata": {},
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}

Search available US phone numbers

GET/api/phone-numbers/available

Numbers the carrier can sell right now, in the United States only. Each includes locality and region where available, and the local-number monthly current price in the carrier's currency, cached per country for 12 hours. Unavailable or failed pricing is null and does not fail the search. Buy one with the purchase route.

Secret API key. How it works

Query parameters

  • area_codestring

    Three-digit US area code, for example 415.

  • containsstring

    Digits the number must contain.

  • limitinteger1 to 100

    How many numbers to return.

Returns

200 OK

Response attributes
  • dataarray of AvailablePhoneNumberrequired

    6 attributes
    • phoneNumberstringrequired

    • localitystring | nullrequired

    • regionstring | nullrequired

    • friendlyNamestring

    • countryCodestring

    • capabilitiesobject

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 503 telephony_not_configured: this deployment has no carrier account
GET /api/phone-numbers/available
curl "https://api.brightshoal.com/api/phone-numbers/available" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"
Response 200
{
  "data": [
    {
      "phoneNumber": "+14155550123",
      "locality": "string",
      "region": "string",
      "friendlyName": "string",
      "countryCode": "string",
      "capabilities": {
        "key": true
      }
    }
  ]
}

Buy a phone number

POST/api/phone-numbers/purchase

Buys a number from the carrier (it is billed from then on) and registers it in the project, unattached. Attach an assistant next to answer calls on it.

Secret API key, not a viewer key. How it works

Request body

  • numberstringrequirednot empty

    The number to purchase in E.164 format, as the search returned it.

  • project_idstring

    Required only for an org-wide key or session.

Returns

201 OK

Response attributes
  • dataPhoneNumberrequired

    15 attributes
    • idstringrequired

    • org_idstring | null

    • project_idstring | null

    • e164stringrequired

    • providerstring | nullrequired

      Null for a customer-owned forwarding number.

    • forward_tostring | null

      The platform E.164 line the customer forwards calls to; null for carrier-managed numbers.

    • provider_number_idstring | null

      The provider's own identifier for the number: Twilio's PN… SID.

    • statusstringrequired

      One of active inactive released

    • capabilitiesobject | null

      What the provider says the number can do: { voice, sms, mms }.

    • routing_modestringrequired

      One of trunk pv_webhook

    • modestringrequired

      Sandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.

      One of live test

    • assistant_idstring | null

    • provider_metadataobject | null

    • created_atstringISO 8601 timestamp

    • updated_atstringISO 8601 timestamp

  • 400 Validation error: usually invalid_request, with the failing fields in issues when there are any
  • 401 Missing, malformed, unknown or revoked API key (unauthorized)
  • 403 Refused, for example a viewer key on a write (read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session
  • 404 Not found, or outside what the key can see
  • 429 Rate limit exceeded (rate_limited). Wait Retry-After seconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
  • 503 telephony_not_configured: this deployment has no carrier account
POST /api/phone-numbers/purchase
curl -X POST "https://api.brightshoal.com/api/phone-numbers/purchase" \
  -H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "number": "+14155550123",
  "project_id": "proj_2f9c41d0a8b34e6f9d1c7a5b3e8f0a12"
}'
Response 201
{
  "data": {
    "id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "org_id": "org_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "e164": "+14155550123",
    "provider": "string",
    "forward_to": "string",
    "provider_number_id": "pn_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "status": "active",
    "capabilities": {},
    "routing_mode": "trunk",
    "mode": "live",
    "assistant_id": "asst_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
    "provider_metadata": {},
    "created_at": "2026-10-28T09:30:00.000Z",
    "updated_at": "2026-10-28T09:30:00.000Z"
  }
}