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. IMPORTANT: You must either specify filters (using the filter parameters) or specific phone numbers (using the phone_numbers parameter in the request body). If you specify filters, ALL phone numbers that match the given filters (up to 1000 at a time) will be updated. If you want to update only specific numbers, you must use the phone_numbers parameter in the request body. When using the phone_numbers parameter, ensure you follow the correct format as shown in the example (either phone number IDs or phone numbers in E164 format).

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/phone_numbers/jobs/update_phone_numbers' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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"
    ],
    "voice": {
        "call_forwarding": {
            "call_forwarding_enabled": true,
            "forwarding_type": "always",
            "forwards_to": "+13035559123"
        }
    }
}'

Response Example

200 - Example 1

{
    "errors": [
        {
            "code": 0,
            "detail": "string",
            "meta": {},
            "source": {
                "parameter": "string",
                "pointer": "/json/pointer"
            },
            "title": "string"
        }
    ]
}

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Query Params

Body Params application/json

Examples

Responses

🟢200OK

application/json

Unexpected error

Body

🟢202Accepted

🟠401Unauthorized

🟠403Forbidden

🟠422Parameter Error

Modified at 2025-06-16 19:14:41

Update the emergency settings from a batch of numbers

Retrieve a phone numbers job