Skip to main content
Each scope unlocks one type of virtual number operation. Grant only what your integration needs.

​
How to send the key

Recommended
Alternative
The API Key belongs to one workspace. You cannot access another workspace with the same key.

​
Common combinations

Query only

phone_numbers:read

Query and configure

phone_numbers:read, phone_numbers:update

Configure inbound only

phone_numbers:update

Full flow

phone_numbers:read, phone_numbers:update
An empty scope list at creation = ADMIN access. Always restrict in production.
Purchasing a number is done in the dashboard. The API queries available numbers, lists workspace numbers, and configures inbound voice.

​
Available scopes

  • List contracted workspace numbers (GET /v1/phone-numbers)
  • Get a number by id (GET /v1/phone-numbers/:id)
  • Search available numbers before dashboard checkout (GET /v1/phone-numbers/available)
Update a number’s configuration (PATCH /v1/phone-numbers/:id): label, inbound voice action (inboundVoiceAction), forwarding, TTS, recording, etc.

​
Relationship with the Voice API

To originate calls with the number, use Voice scopes (voice:call, voice:read, …). Scopes on this page apply only to /v1/phone-numbers.

​
Auth errors

Check Authorization: Bearer sk_... and that the key was not deleted in the dashboard.
Confirm the key has phone_numbers:read or phone_numbers:update for the route.

​
Next steps