Create Task

This request creates a batch task.

post	/batch/tasks

There are three types of batch tasks specified by the method field:

• POST - create new objects
• PATCH - update existing objects
• DELETE - delete existing objects

note

The method field values are not to be confused with the HTTP methods used to make the request. The method field values are used to specify the type of batch task to create, and the HTTP method to create a task object is always POST.

POST - Create New Objects

The data field is used to specify the objects to create. It is an array of objects, each object representing a new object to create.

The type field specifies the type of object to create. Refer to this table to view all types that can be created.

note

The entries and field fields are not used for POST operations and must be set to null or not be included in the request body.

Example Request

An example request to create a batch task that orders two phonenumbers to be added to the same trunk group:

{
    "method": "POST",
    "review": false,
    "type": "phonenumber",
    "data": [
        {
            "phonenumber": "14849687406",
            "trunk_group_sid": "2297adf9-cc6f-45f0-9501-5e8c69d21f11"
        },
        {
            "phonenumber": "14849723113",
            "trunk_group_sid": "2297adf9-cc6f-45f0-9501-5e8c69d21f11"
        }
    ]
}

The following is the cURL POST request to create a batch task:

curl -X POST \
    'https://api.carrierx.com/core/v2/batch/tasks' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${TOKEN}" \
    --data-binary '{"method": "POST", "review": false, "type": "phonenumber", "data": [{"phonenumber": "14849687406", "trunk_group_sid": "2297adf9-cc6f-45f0-9501-5e8c69d21f11"}, {"phonenumber": "14849723113", "trunk_group_sid": "2297adf9-cc6f-45f0-9501-5e8c69d21f11"}]}'

Response

200 status code with a serialized copy of the Task object:

{
  "data": [
    {
      "phonenumber": "14849687406",
      "trunk_group_sid": "2297adf9-cc6f-45f0-9501-5e8c69d21f11"
    },
    {
      "phonenumber": "14849723113",
      "trunk_group_sid": "2297adf9-cc6f-45f0-9501-5e8c69d21f11"
    }
  ],
  "date_created": "2026-04-08T22:04:00.607Z",
  "date_modified": "2026-04-08T22:04:00.607Z",
  "entries": [],
  "failure": null,
  "field": null,
  "method": "POST",
  "partner_sid": "7140b67f-f8a0-428f-a9a9-97c66d6523cb",
  "processed": null,
  "review": false,
  "status": "created",
  "success": null,
  "task_sid": "f3ca0cfc-09da-4744-8764-378d0cc2077c",
  "total": null,
  "type": "phonenumber"
}

PATCH - Update Existing Objects

The entries field is used to specify the objects to update. It is an array of strings, each string representing an object to update.

The field field specifies the field to use to locate the objects to update.

The data field is used to specify the data to update the objects with. It is an object, each key-value pair representing a field to update the objects with.

The type field specifies the type of object to update. Refer to this table to view all types that can be updated.

Example Request

An example request to create a batch task that updates the trunk group of two phonenumbers:

To make it more readable, the JSON payload for the example request is shown below.

{
    "method": "PATCH",
    "type": "phonenumber",
    "review": true,
    "field":"phonenumber",
    "data":{
        "trunk_group_sid": "9070c888-ee95-449b-803b-f2fa082325f8"
    },
    "entries":[
        "14849687406",
        "14849723113"
    ]
}

The following is the cURL PATCH request to create a batch task to update the trunk group of two phonenumbers:

curl -X POST \
    'https://api.carrierx.com/core/v2/batch/tasks' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${TOKEN}" \
    --data-binary '{"method": "PATCH", "type": "phonenumber", "review": true, "field":"phonenumber", "data":{"trunk_group_sid": "9070c888-ee95-449b-803b-f2fa082325f8"}, "entries":["14849687406", "14849723113"]}'

Response

200 status code with a serialized copy of the Task object:

{
  "data": {
    "trunk_group_sid": "9070c888-ee95-449b-803b-f2fa082325f8"
  },
  "date_created": "2026-04-09T00:21:40.402Z",
  "date_modified": "2026-04-09T00:21:40.402Z",
  "entries": [
    "14849687406",
    "14849723113"
  ],
  "failure": null,
  "field": "phonenumber",
  "method": "PATCH",
  "partner_sid": "2a8aed9a-544e-435c-86fc-3378cf9c4127",
  "processed": null,
  "review": true,
  "status": "created",
  "success": null,
  "task_sid": "415d3012-b3a5-4e0f-8c12-49a9cbb12309",
  "total": null,
  "type": "phonenumber"
}

DELETE - Delete Existing Objects

The entries field is used to specify the objects to delete. It is an array of strings, each string representing an object to delete.

The field field specifies the field to use to locate the objects to delete.

The type field specifies the type of object to delete. Refer to this table to view all types that can be deleted.

note

The data field is not used for DELETE operations and must be set to null or not be included in the request body.

Example Request

An example request to create a batch task that deletes two phonenumbers:

To make it more readable, the JSON payload for the example request is shown below.

{
    "method": "DELETE",
    "type": "phonenumber",
    "review": true,
    "field":"phonenumber",
    "entries":[
        "14849687406",
        "14849723113"
    ]
}

The following is the cURL DELETE request to create a batch task to delete two phonenumbers:

curl -X POST \
    'https://api.carrierx.com/core/v2/batch/tasks' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${TOKEN}" \
    --data-binary '{"method": "DELETE", "type": "phonenumber", "review": true, "field":"phonenumber", "entries":["14849687406", "14849723113"]}'

Response

200 status code with a serialized copy of the Task object:

{
  "data": null,
  "date_created": "2026-04-09T00:30:53.619Z",
  "date_modified": "2026-04-09T00:30:53.619Z",
  "entries": [
    "14849687406",
    "14849723113"
  ],
  "failure": null,
  "field": "phonenumber",
  "method": "DELETE",
  "partner_sid": "6e5291c5-f996-4c9d-b7b5-e03d7be7aa95",
  "processed": null,
  "review": true,
  "status": "created",
  "success": null,
  "task_sid": "2f32f2f3-0acf-4aed-8607-b42d5875f4ec",
  "total": null,
  "type": "phonenumber"
}

Required Scopes

To create a Task object, the partner must have one of the following scopes enabled:

• batch.manage
• batch.create

Body Arguments

JSON representation of the fields and values of the Task object to be created.

Required fields to create a batch task depend on the method field value of the Task object:

"method" Field Value	Required Fields
"DELETE"	entries, field, method, type
"PATCH"	data, entries, field, method, type
"POST"	data, method, type

Refer to this table to view all fields that appear in the Task object.