Skip to main content
Cada escopo é uma porta na chave: listar números, contratar linha ou configurar o que fazer quando alguém liga para o seu número. Para discar, use os escopos de Voz.
Cada escopo libera um tipo de operação em números virtuais. Use só o que sua integração precisa.

​
Como enviar a chave

Recomendado
Alternativo
A API Key pertence a um workspace. Você não acessa outro workspace com a mesma chave.

​
Combinações comuns

Só consultar

phone_numbers:read

Consultar e configurar

phone_numbers:read, phone_numbers:update

Só configurar entrada

phone_numbers:update

Fluxo completo

phone_numbers:read, phone_numbers:update, phone_numbers:create, phone_numbers:delete
Lista de escopos vazia na criação = acesso ADMIN. Em produção, restrinja sempre.
Contratar via API: POST /v1/phone-numbers/orders com escopo phone_numbers:create (PIX ou cartão). OAuth regulatório e upload de documentos também via API.

​
Escopos disponíveis

  • Listar números contratados do workspace (GET /v1/phone-numbers)
  • Consultar um número pelo id (GET /v1/phone-numbers/:id)
  • Buscar números disponíveis (GET /v1/phone-numbers/available)
  • Config e preço (GET /v1/phone-numbers/config)
  • Detalhe do pedido (GET /v1/phone-numbers/orders/:orderId)
Atualizar configuração de um número (PATCH /v1/phone-numbers/:id): rótulo, ação de voz de entrada (inboundVoiceAction), encaminhamento, TTS, gravação, etc.
Criar pedido (POST /v1/phone-numbers/orders), perfil regulatório, upload/submit de documentos, seleção de número substituto.
Liberar número (DELETE /v1/phone-numbers/:id) — soft-delete com RELEASED no provedor.

​
Relação com a Voice API

Para originar chamadas com o número, use escopos de Voz (voice:call, voice:read, …). Os escopos desta página valem apenas para /v1/phone-numbers.

​
Erros de autenticação

Confira Authorization: Bearer sk_... e se a chave não foi apagada no painel.
Verifique se a chave tem phone_numbers:read, phone_numbers:update, phone_numbers:create ou phone_numbers:delete conforme a rota.

​
Próximos passos