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, phone_numbers:create, phone_numbers:delete
An empty scope list at creation = ADMIN access. Always restrict in production.
Purchase via API: POST /v1/phone-numbers/orders with scope phone_numbers:create (PIX or card). Regulatory profile, document upload, and submit are also available via API.

​
Available scopes

  • List contracted workspace numbers (GET /v1/phone-numbers)
  • Get a number by id (GET /v1/phone-numbers/:id)
  • Search available numbers (GET /v1/phone-numbers/available)
  • Gateway config and pricing (GET /v1/phone-numbers/config)
  • Order detail (GET /v1/phone-numbers/orders/:orderId)
Update a number’s configuration (PATCH /v1/phone-numbers/:id): label, inbound voice action (inboundVoiceAction), forwarding, TTS, recording, etc.
Create order (POST /v1/phone-numbers/orders), regulatory profile, document upload/submit, replacement number selection.
Release number (DELETE /v1/phone-numbers/:id) — soft-delete with RELEASED at the provider.

​
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, phone_numbers:update, phone_numbers:create, or phone_numbers:delete as required by the route.

​
Next steps