Programmable Voice

Bulk Editing Phone Numbers

Bulk editing allows CarrierX partners to quickly update several phone numbers, files or prefixes, change the trunk group they are associated with, move them to another DID group, assign a new callback URL to all these phone numbers, or add some additional data.

You can modify a single DID using the Update DID API method. But when several phone numbers must be affected with the change, to save time and decrease the load on the CarrierX system network, using the batch editing is strongly recommended. It can update any quantity of DIDs with a single request.

Phone numbers can be modified through the portal and programmatically.

I. Update Phone Numbers Using Portal

In this section, we will go over bulk editing phone numbers through the portal.

To update several phone numbers, log into your CarrierX account. On the left-side menu, locate and click the Configure menu. Click Phone Numbers.

Use the checkboxes to the left of the phone numbers to select them.

Select the numbers you want to modify. The available modification options will appear below the numbers list.

For example, you can select one trunk group from the dropdown list and assign it to two phone numbers at once.

Click Modify Batch when done.

The operation will take some time. After that, the selected phone numbers will be updated.

II. Update DIDs Using REST API

When editing several phone numbers (especially a large number of them), it might be more useful to use the possibilities provided by the Core API. It allows you to update DIDs using either their list, or use advanced filtering to select only the phone numbers, which meet certain requirements.

1. Update DIDs Using Numbers List

Before you can perform any API bulk actions on the rented phone numbers, you will need to decide, which phone numbers you want to edit and how.

You can get the list of all the phone numbers that you have rented from CarrierX, using either the portal, or programmatically. Use the Get DIDs method to list all your rented phone numbers:

curl -X GET \
'https://api.carrierx.com/core/v2/phonenumber/dids' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The response will return the list of all the rented phone numbers. Now you can proceed to modifying this list items.

Create a batch task, which includes:

the list of the DIDs, which are going to be modified, sent as entries attribute,
the method to be used on these DIDs (PATCH),
the type of the object (phonenumber),
the field that will be matched with the entries (phonenumber),
and the parameter, which is going to be modified for all the DIDs (trunk_group_sid).

You can add the review field set to true to the task, so that it is not executed right away, but you have a chance to review it, and either approve or cancel/delete it and create a new one.

curl -X POST \
'https://api.carrierx.com/core/v2/batch/tasks' \
-H 'Content-Type: application/json' \
--data-binary '{"method":"PATCH","type":"phonenumber","field":"phonenumber","entries":["15162065574","15162065584","15162065286","15162065305","15162065306"],"data":{"trunk_group_sid":"b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"},"review":true}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

This task will replace the trunk_group_sid value for all the phone numbers with the new one (b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4), and returns the following response:

{
    "data": {
        "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2020-11-20T20:47:32.517Z",
    "date_modified": "2020-11-20T20:47:32.517Z",
    "entries": [
        "15162065574",
        "15162065584",
        "15162065286",
        "15162065305",
        "15162065306"
    ],
    "error_details": [],
    "failure": null,
    "field": "phonenumber",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": null,
    "review": true,
    "status": "created",
    "success": null,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": null,
    "type": "phonenumber"
}

2. Update DIDs Using Filters

It is not always necessary to have a complete list of DIDs to be able to modify them. Let’s say, you need only the phone numbers from New York locality, which have no trunk groups associated with them.

You can create batch tasks for these phone numbers using filtering.

This is done with the following request:

curl -X POST \
'https://api.carrierx.com/core/v2/batch/tasks' \
-H 'Content-Type: application/json' \
--data-binary '{"method":"PATCH","type":"phonenumber","field":"filter","entries":["locality eq \"NEW YORK\" and trunk_group_sid eq null"],"data":{"trunk_group_sid":"b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"},"review":true}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The request to create the task has the following fields, which differ from the command from step 1:

the phone number filter (locality eq \"NEW YORK\" and trunk_group_sid eq null) instead of the list of the DIDs, sent as the entries attribute,
the field that will be compared against the entries (filter).

The rest of the arguments (method, type, data) as well as the review argument remain the same as in step 1.

This task will also affect all the DIDs from the list above (as all of those phone numbers belong to New York locality and have the trunk_group_sid value equal to null), and will return the following response:

{
    "data": {
        "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2020-11-20T20:47:32.517Z",
    "date_modified": "2020-11-20T20:47:32.517Z",
    "entries": [
        "locality eq \"NEW YORK\" and trunk_group_sid eq null"
    ],
    "error_details": [],
    "failure": null,
    "field": "filter",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": null,
    "review": true,
    "status": "created",
    "success": null,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": null,
    "type": "phonenumber"
}

3. Review Task

Before the task is executed, you might need to review it to make sure that it is going to perform the actions it is supposed to do and does not affect anything it has not been intended for.

The review option is only available if you set the review parameter to true when creating a batch task. If your batch task affect a large number of phone numbers at once, you should very carefully review the task before executing it!

To review a specific task, use the Get Task Review Items by SID method with the secure ID of the task you want to review:

curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2d9e546e-634b-4f6b-97ca-c2158163540c/review_items' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

This request will return the Batch Review Response object with the list of the items, which this task is going to modify, and the fields of these items with their current value and the value that will be set after the task is executed.

{
    "method": "PATCH",
    "review_items": [
        {
            "description": "15162065574",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "43980cda-3608-45d4-8753-d79c1e90b41a",
            "version": 1
        },
        {
            "description": "15162065584",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "5a73b016-3eb7-42f2-84a3-f573a5b5987a",
            "version": 1
        },
        {
            "description": "15162065286",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "b6b119da-7b59-4e28-9982-f53d745ed3a9",
            "version": 1
        },
        {
            "description": "15162065305",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "65942635-4aff-4130-833e-2a0986a097c9",
            "version": 1
        },
        {
            "description": "15162065306",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "902fa7c6-5ee5-418b-bf37-752c307bfb70",
            "version": 1
        }
    ],
    "type": "phonenumber"
}

Here the description field of each item shows the DID number that is going to be modified, and the fields attribute shows an array of the properties to be affected (in our case, the trunk_group_sid is going to be changed for all phone numbers). This array includes the initial property value (null), and the value that is going to be set with the bulk editing task (b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4).

If the list includes only the correct DIDs and their current and future attributes, you can proceed to approving the task.

4. Approve and Execute Task

To approve the bulk editing task, send the PATCH request targeting the task by its secure ID, which will set its status field value to approved:

curl -X PATCH \
'https://api.carrierx.com/core/v2/batch/tasks/2d9e546e-634b-4f6b-97ca-c2158163540c' \
-H 'Content-Type: application/json' \
--data-binary '{"status":"approved"}'\
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The response will show the total number of DIDs, which will be affected by this task, the change of the task status value to approved, and other details of the task:

{
    "data": {
        "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2020-11-20T20:47:32.517Z",
    "date_modified": "2020-11-20T20:57:48.253Z",
    "entries": [
        "locality eq \"NEW YORK\" and trunk_group_sid eq null"
    ],
    "error_details": [],
    "failure": 0,
    "field": "filter",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": 0,
    "review": true,
    "status": "approved",
    "success": 0,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": 5,
    "type": "phonenumber"
}

You can check the status of the batch task using the Get Task by SID method:

curl -X GET \
'https://api.carrierx.com/core/v2/batch/tasks/2d9e546e-634b-4f6b-97ca-c2158163540c' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The response will have the new completed status for the task and will show the number of the processed DIDs (the processed field):

{
    "data": {
        "trunk_group_sid": "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
    },
    "date_created": "2020-11-20T20:47:32.517Z",
    "date_modified": "2020-11-20T20:57:48.253Z",
    "entries": [
        "locality eq \"NEW YORK\" and trunk_group_sid eq null"
    ],
    "error_details": [],
    "failure": 0,
    "field": "filter",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": 5,
    "review": true,
    "status": "completed",
    "success": 5,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": 5,
    "type": "phonenumber"
}

In the case all the DIDs were updated successfully, the number of the successfully updated phone numbers (the success field value) will be equal to the total field value.

If some of the DIDs could not be updated for some reason, the failure field value will be equal to the number of failed phone number updates, and the error_details array will contain the details of the errors, which prevented the DIDs from modifications.

Review the errors and either repeat steps above to create a new batch task, or update the remaining DIDs individually.

III. Further Reading

Refer to the Result Filtering section of the Core API documentation to find out more about the options, which you can use to filter the phone numbers at step 2.

Use the DID Object section of the Core API documentation to view all fields that appear in the DID object, or refer to the Update DID section to learn, which fields can be updated for the DID object.