Open SidemenuAPI Reference
API Reference
Close Sidemenu

Number Background Jobs

Lists the phone numbers jobslistPhoneNumbersJobs

get https://api.telnyx.com/v2/phone_numbers/jobs

Lists the phone numbers jobs

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/phone_numbers/jobs?filter[type]=update_emergency_settings&page[number]=1"
Parameters
In query
filter[type]
string
optional

Identifies the type of the background job.

Example: "update_emergency_settings"
Options: [ "update_emergency_settings", "delete_phone_numbers" ]
page[number]
integer (1)
optional

The page number to load.

Default: 1
page[size]
integer (1 - 250)
optional

The size of the page.

Default: 20
sort
string
optional

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

Example: "created_at"
Options: [ "created_at" ]
Responses
200

Successful response with a list of phone numbers background jobs.

default

Unexpected error

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

Retrieve a phone numbers jobretrievePhoneNumbersJob

get https://api.telnyx.com/v2/phone_numbers/jobs/{id}

Retrieve a phone numbers job

curl -X GET \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --globoff "https://api.telnyx.com/v2/phone_numbers/jobs/{id}"
Parameters
In path
id
string
required

Identifies the Phone Numbers Job.

Responses
200

Phone numbers job details.

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-10-23T18:10:00.000Z",
    "created_by": "015e81fc-11b7-4170-974d-5592ce987da7",
    "etc": "2020-10-30T18:10:00.000Z",
    "failed_operations": [
      {
        "errors": [
          {
            "code": "10015",
            "detail": "The field is invalid.",
            "source": "/emergency_address_id",
            "title": "Bad Request"
          }
        ],
        "id": "3388768018273",
        "phone_number": "+19705551234"
      }
    ],
    "id": "42587e44-3a3e-46de-9255-0c9a7a1d1ec7",
    "record_type": "phone_numbers_job",
    "status": "pending",
    "successful_operations": [
      {
        "id": "2637816387126861836",
        "phone_number": "+19705555098"
      },
      {
        "id": "33081887126861836",
        "phone_number": "+19715555098"
      }
    ],
    "type": "update_emergency_settings",
    "updated_at": "2020-10-23T18:10:01.000Z"
  }
}

Update the emergency settings from a batch of numberscreatePhoneNumbersJobUpdateEmergencySettings

post https://api.telnyx.com/v2/phone_numbers/jobs/update_emergency_settings

Creates a background job to update the emergency settings of a collection of phone numbers. At most one thousand numbers can be updated per API call.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"emergency_address_id":"53829456729313","emergency_enabled":true, "phone_numbers":["+19705555098","+19715555098","32873127836"]}' \
  https://api.telnyx.com/v2/phone_numbers/jobs/update_emergency_settings
Parameters
In body (application/json)
emergency_address_id
string (int64)
required

Identifies the address to be used with emergency services.

emergency_enabled
boolean
required

Indicates whether to enable emergency services on this number.

phone_numbers
array of string
required
Responses
202

Phone numbers enable emergency requested.

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-10-23T18:10:00.000Z",
    "created_by": "015e81fc-11b7-4170-974d-5592ce987da7",
    "etc": "2020-10-30T18:10:00.000Z",
    "failed_operations": [
      {
        "errors": [
          {
            "code": "10015",
            "detail": "The field is invalid.",
            "source": "/emergency_address_id",
            "title": "Bad Request"
          }
        ],
        "id": "3388768018273",
        "phone_number": "+19705551234"
      }
    ],
    "id": "42587e44-3a3e-46de-9255-0c9a7a1d1ec7",
    "record_type": "phone_numbers_job",
    "status": "pending",
    "successful_operations": [
      {
        "id": "2637816387126861836",
        "phone_number": "+19705555098"
      },
      {
        "id": "33081887126861836",
        "phone_number": "+19715555098"
      }
    ],
    "type": "update_emergency_settings",
    "updated_at": "2020-10-23T18:10:01.000Z"
  }
}

Update a batch of numberscreatePhoneNumbersJobUpdatePhoneNumber

post https://api.telnyx.com/v2/phone_numbers/jobs/update_phone_numbers

Creates a new background job to update a batch of numbers. At most one thousand numbers can be updated per API call. At least one of the updateable fields must be submitted

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"phone_numbers":["1583466971586889004","+13127367254"],"billing_group_id":"dc8e4d67-33a0-4cbb-af74-7b58f05bd494"}' \
  https://api.telnyx.com/v2/phone_numbers/jobs/update_phone_numbers
Parameters
In body (application/json)
phone_numbers
array of string
required

Array of phone number ids and/or phone numbers in E164 format to update

billing_group_id
string
optional

Identifies the billing group associated with the phone number.

connection_id
string
optional

Identifies the connection associated with the phone number.

customer_reference
string
optional

A customer reference string for customer look ups.

Example: "MY REF 001"
external_pin
string
optional

If someone attempts to port your phone number away from Telnyx and your phone number has an external PIN set, we will attempt to verify that you provided the correct external PIN to the winning carrier. Note that not all carriers cooperate with this security mechanism.

tags
array of string
optional

A list of user-assigned tags to help organize phone numbers.

Responses
202

Phone numbers job update phone numbers requested.

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-10-23T18:10:00.000Z",
    "created_by": "015e81fc-11b7-4170-974d-5592ce987da7",
    "etc": "2020-10-30T18:10:00.000Z",
    "failed_operations": [
      {
        "errors": [
          {
            "code": "10015",
            "detail": "The field is invalid.",
            "source": "/emergency_address_id",
            "title": "Bad Request"
          }
        ],
        "id": "3388768018273",
        "phone_number": "+19705551234"
      }
    ],
    "id": "42587e44-3a3e-46de-9255-0c9a7a1d1ec7",
    "record_type": "phone_numbers_job",
    "status": "pending",
    "successful_operations": [
      {
        "id": "2637816387126861836",
        "phone_number": "+19705555098"
      },
      {
        "id": "33081887126861836",
        "phone_number": "+19715555098"
      }
    ],
    "type": "update_emergency_settings",
    "updated_at": "2020-10-23T18:10:01.000Z"
  }
}

Delete a batch of numberscreatePhoneNumbersJobDeletePhoneNumbers

post https://api.telnyx.com/v2/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.

curl -X POST \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{"phone_numbers":["+19705555098","+19715555098","32873127836"]}' \
  https://api.telnyx.com/v2/phone_numbers/jobs/delete_phone_numbers
Parameters
In body (application/json)
phone_numbers
array of string
required
Responses
202

Phone numbers job delete phone numbers requested.

default

Unexpected error

Success Response
{
  "data": {
    "created_at": "2020-10-23T18:10:00.000Z",
    "created_by": "015e81fc-11b7-4170-974d-5592ce987da7",
    "etc": "2020-10-30T18:10:00.000Z",
    "failed_operations": [
      {
        "errors": [
          {
            "code": "10015",
            "detail": "The field is invalid.",
            "source": "/emergency_address_id",
            "title": "Bad Request"
          }
        ],
        "id": "3388768018273",
        "phone_number": "+19705551234"
      }
    ],
    "id": "42587e44-3a3e-46de-9255-0c9a7a1d1ec7",
    "record_type": "phone_numbers_job",
    "status": "pending",
    "successful_operations": [
      {
        "id": "2637816387126861836",
        "phone_number": "+19705555098"
      },
      {
        "id": "33081887126861836",
        "phone_number": "+19715555098"
      }
    ],
    "type": "update_emergency_settings",
    "updated_at": "2020-10-23T18:10:01.000Z"
  }
}

Was this section helpful?