API reference
Phone numbers
Search, buy or import numbers, then attach an assistant so it answers inbound calls on that number.
- GET
/api/phone-numbersList phone numbers - POST
/api/phone-numbersImport a phone number you own - GET
/api/phone-numbers/{id}Get a phone number - PATCH
/api/phone-numbers/{id}Set a phone number's sandbox mode - DELETE
/api/phone-numbers/{id}Release a phone number - POST
/api/phone-numbers/{id}/attachAttach an assistant to a phone number - DELETE
/api/phone-numbers/{id}/attachDetach the assistant from a phone number - POST
/api/phone-numbers/{id}/modeChange a phone number's routing mode - GET
/api/phone-numbers/availableSearch available US phone numbers - POST
/api/phone-numbers/purchaseBuy a phone 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_idstringOnly this project's numbers.
Returns
200 OK
Response attributes
dataarray of PhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/phone-numbers" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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_idstringRequired only for an org-wide key.
e164stringrequiredThe number in E.164 format, e.g. +14155550123.
providerstring | nullnot emptyCarrier slug for a managed number. Null or omitted for a customer-owned forwarding number.
forward_tostringRequired for customer-owned numbers. An active platform number in the same project.
provider_metadataobjectCarrier identifiers, for example
{"twilioNumberSid":"PN..."}for a Twilio number.
Returns
201 OK
Response attributes
dataPhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
curl -X POST "https://api.brightshoal.com/api/phone-numbers" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"e164": "+14155550123"
}'{
"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
idstringrequiredPhone number id,
pn_....
Returns
200 OK
Response attributes
dataPhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_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). WaitRetry-Afterseconds. 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).
curl "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredPhone number id,
pn_....
Request body
modestringrequiredOne of
livetest
Returns
200 OK
Response attributes
dataPhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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).
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"
}'{
"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
idstringrequiredPhone number id,
pn_....
Returns
200 OK
Response attributes
dataPhoneNumberReleaserequired3 attributes
idstringrequireddeletedbooleanrequiredreleasedbooleanrequiredWhether 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). WaitRetry-Afterseconds. 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).
curl -X DELETE "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredPhone number id,
pn_....
Request body
assistant_idstringrequirednot emptyrouting_modestringrequiredOne of
trunkpv_webhook
Returns
200 OK
Response attributes
dataPhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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
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"
}'{
"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
idstringrequiredPhone number id,
pn_....
Returns
200 OK
Response attributes
dataPhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_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). WaitRetry-Afterseconds. 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).
curl -X DELETE "https://api.brightshoal.com/api/phone-numbers/PHONE_NUMBER_ID/attach" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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
idstringrequiredPhone number id,
pn_....
Request body
routing_modestringrequiredOne of
trunkpv_webhook
Returns
200 OK
Response attributes
dataPhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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
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"
}'{
"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_codestringThree-digit US area code, for example
415.containsstringDigits the number must contain.
limitinteger1 to 100How many numbers to return.
Returns
200 OK
Response attributes
dataarray of AvailablePhoneNumberrequired6 attributes
phoneNumberstringrequiredlocalitystring | nullrequiredregionstring | nullrequiredfriendlyNamestringcountryCodestringcapabilitiesobject
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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
curl "https://api.brightshoal.com/api/phone-numbers/available" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"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 emptyThe number to purchase in E.164 format, as the search returned it.
project_idstringRequired only for an org-wide key or session.
Returns
201 OK
Response attributes
dataPhoneNumberrequired15 attributes
idstringrequiredorg_idstring | nullproject_idstring | nulle164stringrequiredproviderstring | nullrequiredNull for a customer-owned forwarding number.
forward_tostring | nullThe platform E.164 line the customer forwards calls to; null for carrier-managed numbers.
provider_number_idstring | nullThe provider's own identifier for the number: Twilio's
PN…SID.statusstringrequiredOne of
activeinactivereleasedcapabilitiesobject | nullWhat the provider says the number can do:
{ voice, sms, mms }.routing_modestringrequiredOne of
trunkpv_webhookmodestringrequiredSandbox mode, apart from carrier routing: calls to or from a sandbox number are sandbox calls.
One of
livetestassistant_idstring | nullprovider_metadataobject | nullcreated_atstringISO 8601 timestampupdated_atstringISO 8601 timestamp
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen 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). WaitRetry-Afterseconds. 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
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"
}'{
"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"
}
}