--- title: "Delete a batch of numbers" method: POST path: "/phone_numbers/jobs/delete_phone_numbers" tags: ["Bulk Phone Number Operations"] --- # Delete a batch of numbers `POST /phone_numbers/jobs/delete_phone_numbers` ## Request - Base URL: `https://api.telnyx.com/v2` - URL: `https://api.telnyx.com/v2/phone_numbers/jobs/delete_phone_numbers` - Auth: HTTP bearer Creates a new background job to delete a batch of numbers. At most one thousand numbers can be updated per API call. ## Request body - PhoneNumbersJobDeletePhoneNumbersRequest - `phone_numbers` string[], required ## Response `202` Deletion job accepted. The response contains a background job; poll GET /phone_numbers/jobs/{id} with the job id until it completes. - object - `data` NumbersPhoneNumbersJob - `parameters` object: Effective parameters saved when the job was created, not a snapshot of the original HTTP request or current phone-number settings. Update jobs include the saved update fields; emergency-settings jobs include the saved emergency fields; delete jobs include only targets. Absent fields are omitted, and saved false, null and empty values are preserved. Tags may be normalized to arrays; filter-created jobs contain resolved target identifiers rather than the original filters. Historical jobs with no saved arguments return an empty object. - `phone_numbers` union[]: Saved target phone numbers in E.164 format and/or identifiers. Jobs created using filters contain the resolved identifiers, not the original filter expression. Stored identifier types are preserved. - union - string - integer - `external_pin` string, nullable: Saved external_pin supplied for an update_phone_numbers job. - `connection_id` string, nullable: Saved connection_id supplied for an update_phone_numbers job. - `customer_reference` string, nullable: Saved customer_reference supplied for an update_phone_numbers job. - `billing_group_id` string, nullable: Saved billing_group_id supplied for an update_phone_numbers job. - `hd_voice_enabled` boolean, nullable: Saved hd_voice_enabled supplied for an update_phone_numbers job. - `deletion_lock_enabled` boolean, nullable: Saved deletion_lock_enabled supplied for an update_phone_numbers job. - `tags` string[], nullable: Saved tags for an update_phone_numbers job. Values reflect creation-time normalization. - `add_tags` string[], nullable: Saved add_tags for an update_phone_numbers job. Values reflect creation-time normalization. - `remove_tags` string[], nullable: Saved remove_tags for an update_phone_numbers job. Values reflect creation-time normalization. - `voice` object: Saved voice settings for an update_phone_numbers job, using the public field names and nesting. Only settings present at creation are returned. - `tech_prefix_enabled` boolean, nullable: Saved tech_prefix_enabled setting. - `caller_id_name_enabled` boolean, nullable: Saved caller_id_name_enabled setting. - `usage_payment_method` string, nullable: Saved usage_payment_method setting. - `inbound_call_screening` string, nullable: Saved inbound_call_screening setting. - `call_forwarding` object - `forwards_to` string, nullable: Saved forwards_to setting. - `forwarding_type` string, nullable: Saved forwarding_type setting. - `call_forwarding_enabled` boolean, nullable: Saved call_forwarding_enabled setting. - `call_recording` object - `inbound_call_recording_enabled` boolean, nullable: Saved inbound_call_recording_enabled setting. - `inbound_call_recording_channels` string, nullable: Saved inbound_call_recording_channels setting. - `inbound_call_recording_format` string, nullable: Saved inbound_call_recording_format setting. - `record_continue_on_hold` boolean, nullable: Saved record_continue_on_hold setting. - `media_features` object - `rtp_auto_adjust_enabled` boolean, nullable: Saved rtp_auto_adjust_enabled setting. - `accept_any_rtp_packets_enabled` boolean, nullable: Saved accept_any_rtp_packets_enabled setting. - `t38_fax_gateway_enabled` boolean, nullable: Saved t38_fax_gateway_enabled setting. - `cnam_listing` object - `cnam_listing_enabled` boolean, nullable: Saved cnam_listing_enabled setting. - `cnam_listing_details` string, nullable: Saved cnam_listing_details setting. - `emergency_enabled` boolean, nullable: Saved emergency-services setting for an update_emergency_settings job. - `emergency_address_id` string, nullable: Saved emergency address identifier for an update_emergency_settings job. An explicitly supplied null is preserved. - `id` string, uuid: Identifies the resource. - `record_type` string: Identifies the type of the resource. - `status` 'pending' | 'in_progress' | 'completed' | 'failed' | 'expired': Indicates the completion status of the background update. - `type` 'update_emergency_settings' | 'delete_phone_numbers' | 'update_phone_numbers': Identifies the type of the background job. - `etc` string, date-time: ISO 8601 formatted date indicating when the estimated time of completion of the background job. - `created_at` string: ISO 8601 formatted date indicating when the resource was created. - `updated_at` string: ISO 8601 formatted date indicating when the resource was updated. - `phone_numbers` PhoneNumbersJobPhoneNumber[] - `phone_number` string: The phone number in e164 format. - `id` string: The phone number's ID - `successful_operations` PhoneNumbersJobSuccessfulOperation[] - `phone_number` string: The phone number in e164 format. - `id` string: The phone number's ID - `pending_operations` PhoneNumbersJobPendingOperation[] - `phone_number` string: The phone number in e164 format. - `id` string: The phone number's ID - `failed_operations` NumbersPhoneNumbersJobFailedOperation[] - `phone_number` string: The phone number in e164 format. - `id` string: The phone number's ID - `errors` NumbersError73c9788e53[] - `code` string - `title` string - `detail` string - `source` object - `pointer` string: JSON pointer (RFC6901) to the offending entity. - `parameter` string: Indicates which query parameter caused the error. - `meta` object - `url` string: URL with additional information on the error. ## Other responses - `400`: Bad request, the request was unacceptable, often due to missing a required parameter. - `401`: Unauthorized - `403`: Forbidden - `422`: Unprocessable Entity - `500`: Unexpected error ## Changes - **2026-10-21** `67df31283a8a`: 5 breaking, 5 info - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `400` - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `401` - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `403` - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `422` - …6 more - **2026-10-15** `a72569d69430`: 5 breaking, 5 warning, 11 info - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `400` - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `401` - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `403` - the `errors/items/code` response's property type changed from `string` to `integer`, and format from no format to `int32` for status `422` - …17 more [Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/phone_numbers/jobs/delete_phone_numbers/post.md) --- [API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)