Update a batch of numbers

POST 
/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.

Query Parameters

filter[has_bundle] string

Filter by phone number that have bundles.

filter[tag] string

Filter by phone number tags.

filter[connection_id] int64

Filter by connection_id.

filter[phone_number] string

Filter by phone number. Requires at least three digits. Non-numerical characters will result in no values being returned.

filter[status] string

Possible values: [purchase_pending, purchase_failed, port_pending, active, deleted, port_failed, emergency_only, ported_out, port_out_pending]

Filter by phone number status.

filter[voice.connection_name][contains] string

Filter contains connection name. Requires at least three characters.

filter[voice.usage_payment_method] string

Possible values: [pay-per-minute, channel]

Filter by usage_payment_method.

filter[billing_group_id] string

Filter by the billing_group_id associated with phone numbers. To filter to only phone numbers that have no billing group associated them, set the value of this filter to the string 'null'.

filter[emergency_address_id] int64

Filter by the emergency_address_id associated with phone numbers. To filter only phone numbers that have no emergency address associated with them, set the value of this filter to the string 'null'.

filter[customer_reference] string

Filter numbers via the customer_reference set.

application/json

Body

required

phone_numbers string[]required

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

tags string[]

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

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.

customer_reference string

A customer reference string for customer look ups.

connection_id string

Identifies the connection associated with the phone number.

billing_group_id string

Identifies the billing group associated with the phone number.

hd_voice_enabled boolean

Indicates whether to enable or disable HD Voice on each phone number. HD Voice is a paid feature and may not be available for all phone numbers, more details about it can be found in the Telnyx support documentation.

voice

object

tech_prefix_enabled boolean

Controls whether a tech prefix is enabled for this phone number.

translated_number string

This field allows you to rewrite the destination number of an inbound call before the call is routed to you. The value of this field may be any alphanumeric value, and the value will replace the number originally dialed.

caller_id_name_enabled boolean

Controls whether the caller ID name is enabled for this phone number.

call_forwarding

object

The call forwarding settings for a phone number.

call_forwarding_enabled boolean

Default value: true

Indicates if call forwarding will be enabled for this number if forwards_to and forwarding_type are filled in. Defaults to true for backwards compatibility with APIV1 use of numbers endpoints.

forwards_to string

The phone number to which inbound calls to this number are forwarded. Inbound calls will not be forwarded if this field is left blank. If set, must be a +E.164-formatted phone number.

forwarding_type string

Possible values: [always, on_failure]

Call forwarding type. 'forwards_to' must be set for this to have an effect.

The call forwarding settings for a phone number.

cnam_listing

object

The CNAM listing settings for a phone number.

cnam_listing_enabled boolean

Enables CNAM listings for this number. Requires cnam_listing_details to also be set.

cnam_listing_details string

The CNAM listing details for this number. Must be alphanumeric characters or spaces with a maximum length of 15. Requires cnam_listing_enabled to also be set to true.

The CNAM listing settings for a phone number.

usage_payment_method string

Possible values: [pay-per-minute, channel]

Default value: pay-per-minute

Controls whether a number is billed per minute or uses your concurrent channels.

media_features

object

The media features settings for a phone number.

rtp_auto_adjust_enabled boolean

Default value: true

When RTP Auto-Adjust is enabled, the destination RTP address port will be automatically changed to match the source of the incoming RTP packets.

accept_any_rtp_packets_enabled boolean

When enabled, Telnyx will accept RTP packets from any customer-side IP address and port, not just those to which Telnyx is sending RTP.

t38_fax_gateway_enabled boolean

Controls whether Telnyx will accept a T.38 re-INVITE for this phone number. Note that Telnyx will not send a T.38 re-INVITE; this option only controls whether one will be accepted.

The media features settings for a phone number.

call_recording

object

The call recording settings for a phone number.

inbound_call_recording_enabled boolean

When enabled, any inbound call to this number will be recorded.

inbound_call_recording_format string

Possible values: [wav, mp3]

Default value: wav

The audio file format for calls being recorded.

inbound_call_recording_channels string

Possible values: [single, dual]

Default value: single

When using 'dual' channels, final audio file will be stereo recorded with the first leg on channel A, and the rest on channel B.

The call recording settings for a phone number.

inbound_call_screening string

Possible values: [disabled, reject_calls, flag_calls]

Default value: disabled

The inbound_call_screening setting is a phone number configuration option variable that allows users to configure their settings to block or flag fraudulent calls. It can be set to disabled, reject_calls, or flag_calls. This feature has an additional per-number monthly cost associated with it.

202: Phone numbers job update phone numbers requested.

application/json

• Schema
• Example (from schema)

Schema

data

object

id uuid

Identifies the resource.

record_type string

Identifies the type of the resource.

status string

Possible values: [pending, in_progress, completed, failed, expired]

Default value: pending

Indicates the completion status of the background update.

type string

Possible values: [update_emergency_settings, delete_phone_numbers, update_phone_numbers]

Identifies the type of the background job.

etc 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[]

Array [

phone_number e164

The phone number in e164 format.

id int64

The phone number's ID

]

successful_operations

PhoneNumbersJobSuccessfulOperation[]

Array [

phone_number e164

The phone number in e164 format.

id int64

The phone number's ID

]

pending_operations

PhoneNumbersJobPendingOperation[]

Array [

phone_number e164

The phone number in e164 format.

id int64

The phone number's ID

]

failed_operations

PhoneNumbersJobFailedOperation[]

Array [

phone_number e164

The phone number in e164 format.

id int64

The phone number's ID

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

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.

]

]

{
  "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": "/emergency_address_id"
          }
        ]
      }
    ]
  }
}

401: Unauthorized

application/json

• Schema
• Example (from schema)
• Authentication Failed

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

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.

]

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10009",
      "title": "Authentication failed",
      "detail": "Could not understand the provided credentials.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10009"
      }
    }
  ]
}

403: Forbidden

application/json

• Schema
• Example (from schema)
• Not authorized
• Billing group not authorized

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

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.

]

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10006",
      "title": "Not authorized",
      "detail": "You are not authorized to access the requested resource.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10006"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10010",
      "title": "Authorization Failed",
      "detail": "The specified billing group either does not exist or is not part of your account",
      "source": {
        "pointer": "/billing_group_id"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10010"
      }
    }
  ]
}

422: Unprocessable Entity

application/json

• Schema
• Example (from schema)
• Phone numbers must be present
• Maximum allowed phone numbers
• Minimum allowed phone numbers
• Mixed IDs and E164 values
• Phone number ownership
• Minimum updateable field
• Maximum jobs allowed

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

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.

]

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "must be present",
      "source": {
        "pointer": "/phone_numbers"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "1000 numbers is the maximum allowed.",
      "source": {
        "pointer": "/phone_numbers"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "You must provide at least 1 phone number.",
      "source": {
        "pointer": "/phone_numbers"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "You must specify either all phone numbers in the e164 format or all as phone number ids",
      "source": {
        "pointer": "/phone_numbers"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "You must own every number in the bulk request",
      "source": {
        "pointer": "/phone_numbers"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "You must provide at least 1 updateable field.",
      "source": {
        "pointer": "/updateable_fields"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "You can have at most 20 pending or in progress jobs",
      "source": {
        "pointer": "/base"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

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.

]

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/phone_numbers/jobs/update_phone_numbers' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "phone_numbers": [
    "1583466971586889004",
    "+13127367254"
  ],
  "tags": [
    "tag"
  ],
  "external_pin": "123456",
  "customer_reference": "customer-reference",
  "connection_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  "billing_group_id": "dc8e4d67-33a0-4cbb-af74-7b58f05bd494",
  "voice": {
    "call_forwarding": {
      "call_forwarding_enabled": true,
      "forwards_to": "+13035559123",
      "forwarding_type": "always"
    }
  }
}'

Response samples

• 202
• 401
• 403
• 422
• default

---

{
  "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": "/emergency_address_id"
          }
        ]
      }
    ]
  }
}

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10007",
      "title": "Unexpected error",
      "detail": "An unexpected error occured.",
      "source": {
        "pointer": "/base",
        "parameter": "string"
      },
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}