Bulk Phone Number Operations

Lists the phone numbers jobs

Changed on

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.

get/phone_numbers/jobs

Request

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

Query parameters

sizeinteger

The size of the page

numberinteger

The page number to load

Consolidated page parameter (deepObject style). Originally: page[size], page[number]

sort'created_at'
Example:created_at

Specifies the sort order for results. If not given, results are sorted by created_at in descending order.

type'update_emergency_settings' | 'delete_phone_numbers' | 'update_phone_numbers'

Identifies the type of the background job.

customer_referencestring

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.

statusstring[]

Returns jobs with any of the supplied statuses. Use repeated filter[status][] parameters; scalar and comma-separated status values are not accepted.

Consolidated filter parameter (deepObject style). Originally: filter[type], filter[phone_number], filter[phone_number][], filter[status][], filter[customer_reference]

{
  "type": "update_emergency_settings",
  "customer_reference": "yourcustomerrefhere",
  "phone_number": "+15551234567,1234567890123456789",
  "status": [
    "pending",
    "in_progress"
  ]
}

Response

Successful response with a list of phone numbers background jobs.

Example response

{
  "data": [
    {
      "id": "42587e44-3a3e-46de-9255-0c9a7a1d1ec7",
      "record_type": "phone_numbers_job",
      "status": "pending",
      "type": "update_emergency_settings",
      "etc": "2020-10-30T18:10:00.000Z",
      "created_at": "2020-10-23T18:10:00.000Z",
      "updated_at": "2020-10-23T18:10:01.000Z",
      "phone_numbers": [
        {
          "id": "2637816387126861836"
        },
        {
          "phone_number": "+19715555098"
        },
        {
          "phone_number": "+19705555099"
        },
        {
          "id": "3388768018273"
        }
      ],
      "successful_operations": [
        {
          "id": "2637816387126861836",
          "phone_number": "+19705555098"
        },
        {
          "id": "33081887126861836",
          "phone_number": "+19715555098"
        }
      ],
      "pending_operations": [
        {
          "id": "2637816387126861837",
          "phone_number": "+19705555099"
        }
      ],
      "failed_operations": [
        {
          "id": "3388768018273",
          "phone_number": "+19705551234",
          "errors": [
            {
              "code": "10015",
              "title": "Bad Request",
              "detail": "The field is invalid.",
              "source": {
                "pointer": "/emergency_address_id"
              }
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "total_pages": 3,
    "total_results": 55,
    "page_number": 2,
    "page_size": 25
  }
}

Changes

  • 19db5ee4ec59Revision changes
    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • breaking

      the // response's property type changed from integer to string, and format from int32 to no format for status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • da303e40b51eRevision changes
    • info

      added the optional property // to the response with the status