---
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`

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` PhoneNumbersJob
    - `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` PhoneNumbersJobFailedOperation[]
      - `phone_number` string — The phone number in e164 format.
      - `id` string — The phone number's ID
      - `errors` NumbersError[]
        - `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

> 78 revisions in range; 1 not diffed.

- **2026-09-16** `a6a61a29ecdd` — 5 breaking, 5 warning, 10 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`
  - …16 more
- **2026-08-17** `1571b0380bd7` — 15 breaking, 5 info
  - the response property `errors/items/code` became optional for the status `400`
  - the response property `errors/items/code` became optional for the status `401`
  - the response property `errors/items/code` became optional for the status `403`
  - the response property `errors/items/code` became optional for the status `422`
  - …16 more
- …earlier changes not shown

[Full history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/phone_numbers/jobs/delete_phone_numbers/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/950384d11a37?raw)