Programmable Voice

Bulk Editing Prefixes

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

You can modify a single prefix using the Update Prefix API method. But when several prefixes 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 prefixes with a single request.

Prefixes can be modified through the portal and programmatically.

I. Update Prefixes Using Portal

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

To update several prefixes, log into your CarrierX account. On the left-side menu, locate and click the Configure menu. Click Prefixes.

Use the checkboxes to the left of the prefixes to select them.

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

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

Click Modify Batch when done.

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

II. Update Prefixes Using REST API

When editing several prefixes (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 prefixes using either their list, or use advanced filtering to select only the prefixes, which meet certain requirements.

1. Update Prefixes Using List

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

You can get the list of all the prefixes using either the portal, or programmatically. Use the Get Prefixes method to list all your existing prefixes:

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

The response will return the list of all the currently existing prefixes. Now you can proceed to modifying this list items.

Create a batch task, which includes:

the list of the prefixes, which are going to be modified, sent as entries attribute,
the method to be used on these prefixes (PATCH),
the type of the object (prefix),
the field that will be matched with the entries (prefix),
and the parameter, which is going to be modified for all the prefixes (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":"prefix","field":"prefix","entries":["999","9999","99999"],"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 prefixes 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": [
        "999",
        "9999",
        "99999"
    ],
    "error_details": [],
    "failure": null,
    "field": "prefix",
    "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": "prefix"
}

2. Update Prefixes Using Filters

It is not always necessary to have a complete list of prefixes to be able to modify them. Let’s say, you need only the prefixes that start with 999, which have no trunk groups associated with them.

You can create batch tasks for these prefixes 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":"prefix","field":"filter","entries":["prefix like 999% 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 prefix filter (prefix like 999% and trunk_group_sid eq null) instead of the list of the prefixes, 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 prefixes from the list above (as all of those prefixes start with 999 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": [
        "prefix like 999% 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": "prefix"
}

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 prefixes 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": "999",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "43980cda-3608-45d4-8753-d79c1e90b41a",
            "version": 1
        },
        {
            "description": "9999",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "5a73b016-3eb7-42f2-84a3-f573a5b5987a",
            "version": 1
        },
        {
            "description": "99999",
            "fields": {
                "trunk_group_sid": [
                    null,
                    "b30a3dbb-3708-41f0-a9ca-5cf365dcc4d4"
                ]
            },
            "sid": "b6b119da-7b59-4e28-9982-f53d745ed3a9",
            "version": 1
        }
    ],
    "type": "prefix"
}

Here the description field of each item shows the prefix 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 prefixes). 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 prefixes 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 prefixes, 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": [
        "prefix like 999% 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": 3,
    "type": "prefix"
}

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 prefixes (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": [
        "prefix like 999% and trunk_group_sid eq null"
    ],
    "error_details": [],
    "failure": 0,
    "field": "filter",
    "method": "PATCH",
    "partner_sid": "923840ce-0b63-44a9-b4ce-09dc4181fb9d",
    "processed": 3,
    "review": true,
    "status": "completed",
    "success": 3,
    "task_sid": "2d9e546e-634b-4f6b-97ca-c2158163540c",
    "total": 3,
    "type": "prefix"
}

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

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

Review the errors and either repeat steps above to create a new batch task, or update the remaining prefixes 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 prefixes at step 2.

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