---
title: "Lists the phone numbers jobs"
method: GET
path: "/phone_numbers/jobs"
tags: ["Bulk Phone Number Operations"]
---

# Lists the phone numbers jobs

`GET /phone_numbers/jobs`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/phone_numbers/jobs`
- Auth: HTTP bearer

Returns background jobs that operate on phone numbers. Filter by job type, target phone numbers, job status, or creation-time customer reference, and sort by creation time. Multiple phone-number or status values use OR semantics within that filter; different filter categories use AND semantics. Results include pagination metadata.

## Query parameters

- `page` object
  - `size` integer: The size of the page
  - `number` integer: The page number to load
- `sort` 'created_at'
- `filter` object
  - `type` 'update_emergency_settings' | 'delete_phone_numbers' | 'update_phone_numbers': Identifies the type of the background job.
  - `customer_reference` string: Exact, case-sensitive match for the customer reference supplied when the job was created. Only jobs created within the last 90 days are returned, including for accounts otherwise exempt from job retention limits. Searches the stored job reference, not the current reference on a phone number. Multiple jobs may share a reference. Combines with the other filters and account ownership. Supply a single non-blank string of up to 250 characters, without null characters, using `filter[customer_reference]=yourcustomerrefhere`. Whitespace is preserved; blank strings, arrays, and objects return HTTP 422. An invalid filter value returns HTTP 422. The literal string `null` is matched as text.
  - `phone_number` union: Returns jobs that targeted any of the supplied account-owned phone numbers. Values beginning with `+` must contain 1 to 20 digits after the plus sign. The 10-value limit is enforced before duplicate values are removed. Unmatched or non-account-owned identifiers return an empty result. Phone-number filtering must be enabled for the account.
    - string: One E.164 phone number or Telnyx Phone Number ID, or a comma-separated list of up to 10 values.
    - string[]: Up to 10 E.164 phone numbers or Telnyx Phone Number IDs. Use repeated `filter[phone_number][]` parameters.
  - `status` string[]: Returns jobs with any of the supplied statuses. Use repeated `filter[status][]` parameters; scalar and comma-separated status values are not accepted.

## Response `200`

Successful response with a list of phone numbers background jobs.

- 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.
  - `meta` PaginationMeta
    - `total_pages` integer
    - `total_results` integer
    - `page_number` integer
    - `page_size` integer

## Other responses

- `400`: Bad request, the request was unacceptable, often due to missing a required parameter.
- `401`: Unauthorized
- `422`: Unprocessable Entity
- `500`: Unexpected error

## Changes

- **2026-10-21** `67df31283a8a`: 4 breaking, 4 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 `422`
  - the `errors/items/code` response's property type changed from `integer` to `string`, and format from `int32` to no format for status `500`
  - …4 more
- **2026-10-15** `a72569d69430`: 6 breaking, 6 warning, 10 info
  - the response property `meta/page_number` became optional for the status `200`
  - the response property `meta/total_pages` became optional for the status `200`
  - 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`
  - …18 more

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/phone_numbers/jobs/get.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)