Route a number to an agent
Assign a workspace phone number (by its id from list_phone_numbers) to an agent, so calls to that number reach the agent. For a number on our carrier this also points it at this environment's voice connection, so a number that previously routed elsewhere (another env, an old local tunnel, an outbound-only caller ID) starts ringing here, that repoint is what makes the assignment real, so it runs before the binding and the whole call fails if it can't. This is also the repair for the connection drift reconcile_phone_numbers reports.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Target agent as 'workspace-slug/agent-slug'.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/workspaces/string/phone-numbers/string/assign" \ -H "Content-Type: application/json" \ -d '{ "agent": "string" }'{
"phoneNumber": "string",
"agent": "string",
"property1": null,
"property2": null
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Register a phone number POST
Register a phone number the workspace ALREADY OWNS at the provider (e.g. a number ordered from or ported to the carrier out-of-band) into the workspace, so it appears in list_phone_numbers and can be assigned to an agent with assign_phone_number. This does NOT purchase or port a number, order/port it with the provider first (attaching the right voice connection there), then register it here. Numbers on our carrier are verified against the carrier's LIVE state before the row is written: the providerSid must exist and match the number, and its voice connection must route to THIS environment's runtime. A number answered by another environment is refused (pass allowCrossEnvRouting: true to register it anyway, for a deliberate split-env setup). Routing metadata is read from the carrier, so connectionId/connectionName args are ignored when they disagree with the live record. Added unbilled (no Stripe rental enrolment; prices stay null), matching the demo-line pattern. Idempotent on the phone number, re-adding one already in this workspace returns it unchanged.
List phone numbers GET
List the phone numbers provisioned in a workspace, with provider, status, friendly name, the monthly price in cents, when it was bought, and the id of the agent it answers for (null when unassigned). Assign one to an agent with assign_phone_number.