Phone Numbers

Manage the phone numbers associated with your organization. Provision toll-free or local numbers via Telnyx, configure how incoming calls are handled, and release numbers when no longer needed.

POST /numbers

Provision a new phone number for your organization. Searches available Telnyx inventory, places an order, and registers the number to your account.

Request body

Request example

JSON

Response (201)

JSON

New numbers are provisioned with incoming_call_action set to auto_reject. Update the number to configure how incoming calls are handled.

Error responses

Code examples

cURL

cURL

JavaScript

Python

DELETE /numbers/{phone_number_id}

Release a phone number from your organization. The number is deleted in Inkbox with status released and unlinked from any identity. Returns 204 No Content on success.

Caution: Releasing a number is irreversible. The number is returned to the carrier pool and you may not be able to reclaim it.

Path parameters

Response (204)

Returns no content.

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /numbers

List all phone numbers for your organization.

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

GET /numbers/{phone_number_id}

Get a single phone number by ID.

Path parameters

Response (200)

Returns a phone number object.

Error responses

Code examples

cURL

cURL

JavaScript

Python

PATCH /numbers/{phone_number_id}

Update the configuration for a phone number. All fields are optional — only the fields you provide will be updated.

Path parameters

Request body

Request example

JSON

Response (200)

Returns the updated phone number object. When this request changes filter_mode to a new value, the response also includes a filter_mode_change_notice object counting rules that are now redundant under the new mode (see the Phone number object below). The field is null on any other PATCH and on GET, list, and create responses.

Error responses

Code examples

cURL

cURL

JavaScript

Python

filter_mode_change_notice

• Phone contact rules — the allow/block list interpreted by filter_mode
• Filtering guide — whitelist/blacklist walkthrough for mail and phone