Bulk Number Operations API

Background jobs performed over a batch of phone numbers using API

Lists the phone numbers jobs

SecuritybearerAuth
Request
query Parameters
filter[type]
string

Filter the phone number jobs by type.

Enum: "update_emergency_settings" "delete_phone_numbers" "update_phone_numbers"
Example: filter[type]=update_emergency_settings
page[number]
integer >= 1
Default: 1

The page number to load

page[size]
integer [ 1 .. 250 ]
Default: 20

The size of the page

sort
string

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

Value: "created_at"
Example: sort=created_at
Responses
200

Successful response with a list of phone numbers background jobs.

Response Schema: application/json
Array of objects (PhoneNumbersJob)
object (PaginationMeta)
default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers/jobs
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const {data: numberJobs} = await telnyx.numberBackgroundJobs.list();
Response samples
application/json
{
  • "data": [
    • {
      • "created_at": "2020-10-23T18:10:00.000Z",
      • "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",
      • "pending_operations": [
        • {
          • "id": "2637816387126861837",
          • "phone_number": "+19705555099"
          }
        ],
      • "phone_numbers": [
        • {
          • "id": "2637816387126861836"
          },
        • {
          • "phone_number": "+19715555098"
          },
        • {
          • "phone_number": "+19705555099"
          },
        • {
          • "id": "3388768018273"
          }
        ],
      • "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
    }
}

Delete a batch of numbers

Creates a new background job to delete a batch of numbers. At most one thousand numbers can be updated per API call.

SecuritybearerAuth
Request
Request Body schema: application/json
required
phone_numbers
required
Array of strings
Responses
202

Phone numbers job delete phone numbers requested.

Response Schema: application/json
object (PhoneNumbersJob)
created_at
string

ISO 8601 formatted date indicating when the resource was created.

etc
string <date-time>

ISO 8601 formatted date indicating when the estimated time of completion of the background job.

Array of objects (PhoneNumbersJobFailedOperation)
id
string <uuid>

Identifies the resource.

Array of objects (PhoneNumbersJobPendingOperation)
Array of objects (PhoneNumbersJobPhoneNumber)
record_type
string

Identifies the type of the resource.

status
string
Default: "pending"

Indicates the completion status of the background update.

Enum: "pending" "in_progress" "completed" "failed" "expired"
Array of objects (PhoneNumbersJobSuccessfulOperation)
type
string

Identifies the type of the background job.

Enum: "update_emergency_settings" "delete_phone_numbers" "update_phone_numbers"
updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
post/phone_numbers/jobs/delete_phone_numbers
Request samples
application/json
{
  • "phone_numbers": [
    • "+19705555098",
    • "+19715555098",
    • "32873127836"
    ]
}
Response samples
application/json
{
  • "data": {
    • "created_at": "2020-10-23T18:10:00.000Z",
    • "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",
    • "pending_operations": [
      • {
        • "id": "2637816387126861837",
        • "phone_number": "+19705555099"
        }
      ],
    • "phone_numbers": [
      • {
        • "id": "2637816387126861836"
        },
      • {
        • "phone_number": "+19715555098"
        },
      • {
        • "phone_number": "+19705555099"
        },
      • {
        • "id": "3388768018273"
        }
      ],
    • "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 numbers

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.

SecuritybearerAuth
Request
Request Body schema: application/json
required
emergency_address_id
required
string <int64>

Identifies the address to be used with emergency services.

emergency_enabled
required
boolean

Indicates whether to enable emergency services on this number.

phone_numbers
required
Array of strings
Responses
202

Phone numbers enable emergency requested.

Response Schema: application/json
object (PhoneNumbersJob)
created_at
string

ISO 8601 formatted date indicating when the resource was created.

etc
string <date-time>

ISO 8601 formatted date indicating when the estimated time of completion of the background job.

Array of objects (PhoneNumbersJobFailedOperation)
id
string <uuid>

Identifies the resource.

Array of objects (PhoneNumbersJobPendingOperation)
Array of objects (PhoneNumbersJobPhoneNumber)
record_type
string

Identifies the type of the resource.

status
string
Default: "pending"

Indicates the completion status of the background update.

Enum: "pending" "in_progress" "completed" "failed" "expired"
Array of objects (PhoneNumbersJobSuccessfulOperation)
type
string

Identifies the type of the background job.

Enum: "update_emergency_settings" "delete_phone_numbers" "update_phone_numbers"
updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
post/phone_numbers/jobs/update_emergency_settings
Request samples
application/json
{
  • "emergency_address_id": "53829456729313",
  • "emergency_enabled": true,
  • "phone_numbers": [
    • "+19705555098",
    • "+19715555098",
    • "32873127836"
    ]
}
Response samples
application/json
{
  • "data": {
    • "created_at": "2020-10-23T18:10:00.000Z",
    • "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",
    • "pending_operations": [
      • {
        • "id": "2637816387126861837",
        • "phone_number": "+19705555099"
        }
      ],
    • "phone_numbers": [
      • {
        • "id": "2637816387126861836"
        },
      • {
        • "phone_number": "+19715555098"
        },
      • {
        • "phone_number": "+19705555099"
        },
      • {
        • "id": "3388768018273"
        }
      ],
    • "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 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.

SecuritybearerAuth
Request
Request Body schema: application/json
required
billing_group_id
string

Identifies the billing group associated with the phone number.

connection_id
string

Identifies the connection associated with the phone number.

customer_reference
string

A customer reference string for customer look ups.

external_pin
string

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.

phone_numbers
required
Array of strings

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

tags
Array of strings

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

Responses
202

Phone numbers job update phone numbers requested.

Response Schema: application/json
object (PhoneNumbersJob)
created_at
string

ISO 8601 formatted date indicating when the resource was created.

etc
string <date-time>

ISO 8601 formatted date indicating when the estimated time of completion of the background job.

Array of objects (PhoneNumbersJobFailedOperation)
id
string <uuid>

Identifies the resource.

Array of objects (PhoneNumbersJobPendingOperation)
Array of objects (PhoneNumbersJobPhoneNumber)
record_type
string

Identifies the type of the resource.

status
string
Default: "pending"

Indicates the completion status of the background update.

Enum: "pending" "in_progress" "completed" "failed" "expired"
Array of objects (PhoneNumbersJobSuccessfulOperation)
type
string

Identifies the type of the background job.

Enum: "update_emergency_settings" "delete_phone_numbers" "update_phone_numbers"
updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
post/phone_numbers/jobs/update_phone_numbers
Request samples
application/json
{
  • "billing_group_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  • "connection_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  • "customer_reference": "customer-reference",
  • "external_pin": "123456",
  • "phone_numbers": [
    • "1583466971586889004",
    • "+13127367254"
    ],
  • "tags": [
    • "tag"
    ]
}
Response samples
application/json
{
  • "data": {
    • "created_at": "2020-10-23T18:10:00.000Z",
    • "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",
    • "pending_operations": [
      • {
        • "id": "2637816387126861837",
        • "phone_number": "+19705555099"
        }
      ],
    • "phone_numbers": [
      • {
        • "id": "2637816387126861836"
        },
      • {
        • "phone_number": "+19715555098"
        },
      • {
        • "phone_number": "+19705555099"
        },
      • {
        • "id": "3388768018273"
        }
      ],
    • "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"
    }
}

Retrieve a phone numbers job

SecuritybearerAuth
Request
path Parameters
id
required
string

Identifies the Phone Numbers Job.

Responses
200

Phone numbers job details.

Response Schema: application/json
object (PhoneNumbersJob)
created_at
string

ISO 8601 formatted date indicating when the resource was created.

etc
string <date-time>

ISO 8601 formatted date indicating when the estimated time of completion of the background job.

Array of objects (PhoneNumbersJobFailedOperation)
id
string <uuid>

Identifies the resource.

Array of objects (PhoneNumbersJobPendingOperation)
Array of objects (PhoneNumbersJobPhoneNumber)
record_type
string

Identifies the type of the resource.

status
string
Default: "pending"

Indicates the completion status of the background update.

Enum: "pending" "in_progress" "completed" "failed" "expired"
Array of objects (PhoneNumbersJobSuccessfulOperation)
type
string

Identifies the type of the background job.

Enum: "update_emergency_settings" "delete_phone_numbers" "update_phone_numbers"
updated_at
string

ISO 8601 formatted date indicating when the resource was updated.

default

Unexpected error

Response Schema: application/json
Array of objects (Error)
Array
code
required
string <int>
detail
string
meta
object
object
title
required
string
get/phone_numbers/jobs/{id}
Request samples 
const telnyx = require('telnyx')('YOUR_API_KEY');

const {data: numberJob} = await telnyx.numberBackgroundJobs.retrieve('123');
Response samples
application/json
{
  • "data": {
    • "created_at": "2020-10-23T18:10:00.000Z",
    • "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",
    • "pending_operations": [
      • {
        • "id": "2637816387126861837",
        • "phone_number": "+19705555099"
        }
      ],
    • "phone_numbers": [
      • {
        • "id": "2637816387126861836"
        },
      • {
        • "phone_number": "+19715555098"
        },
      • {
        • "phone_number": "+19705555099"
        },
      • {
        • "id": "3388768018273"
        }
      ],
    • "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"
    }
}