Telephony
Manage Truedy-managed phone numbers and assignments: list, search, purchase, assign, unassign, release (delete) numbers, and get agent numbers and webhook URLs. BYOC credential and provider configuration workflows remain dashboard/private capabilities.List Numbers
Query:limit (default 50, max 100), offset (default 0). Returns all phone numbers for your organization (Truedy-managed and BYOC).
Search Numbers
Body:country_code (default "US"), locality (city/region), area_code (e.g. 212), administrative_area (state/province), phone_number_type (e.g. local, toll_free, mobile, national), features, best_effort, reservable, exclude_held_numbers, quickship, limit, api_key (optional Telnyx key), page (default 1), and page_size (default 20, max 100). All listed search filters are forwarded to the provider. Response includes data and pagination (page, page_size, total_results, total_pages, has_more).
Purchase Number
Purchase a Truedy-managed phone number through the API. The number must come from the available-number search results and must be sent in E.164 format. Authentication: Include your Truedy API key as a bearer token. Idempotency:X-Idempotency-Key is required. Generate a unique value for each intended purchase and reuse that same value when retrying an uncertain request. Reusing it with a different payload is rejected. Truedy reconciles an uncertain provider response before it will accept another purchase attempt.
The response contains the purchased number in
data, including its id, phone_number, status, and is_truedy_managed fields. Use the returned id when assigning the number to an agent.
Errors:
- 422 — The number is invalid, unavailable, or the organization’s telephony provider is not configured.
- 401 — The API key is missing or invalid.
- 409 — The idempotency key conflicts with another payload, the original request is still running, or an uncertain provider outcome is still being reconciled.
- 429 — The request exceeded the API rate limit.
- 502/503 — The provider or the idempotency/reconciliation store is temporarily unavailable. Retry with the same idempotency key.
Assign Number
Body:number_id (UUID), agent_id (UUID), assignment_type ("inbound" or "outbound"). Required for outbound calls: assign at least one number to the agent for outbound before creating outbound calls.
Unassign Number
Body:number_id (UUID), assignment_type ("inbound" or "outbound").
Delete (Release) Number
Releases a phone number. Truedy-managed numbers are released from the provider; BYOC numbers are removed from your organization only. Path:number_id — UUID of the number (from list or assign).
Get Agent Numbers
Returns inbound and outbound numbers assigned to the agent. Path:agent_id — agent UUID.
Get Webhook URL
Returns the agent webhook URL for BYOC (Bring Your Own Carrier) setup. Path:agent_id — agent UUID.
Note: Purchase may return 422 when the telephony provider is not configured for your organization. Assign/unassign require valid number_id and assignment_type.