Task API V3 — Developer Guide

• Applies to: Sprinklr Task API V3 (/api/v3/task)
• V2 API reference: Task | Sprinklr Developer Portal

A Sprinklr Task is a standard business object used in Modern Marketing to track and manage content using configurable agile Production Dashboards. A task is always created against an entity — a message, a campaign, an asset — identified by assetId and assetType, and it carries assignment, status, due-date, queue, subscriber, and custom-field state.

Task V3 exposes full CRUD on a single resource path — /api/v3/task and differentiates operations by HTTP method, with bulk support on the read, delete, and update paths through a comma-separated ?id= query parameter.

Note: Request and response schemas differ. POST and PUT operations accept a TaskRequest object, while read operations return a Task object. These schemas are not interchangeable.

Note: Write operations use queueIds (Array[String]), while read operations return queueDetails (Array[Queue]). Because these fields use different schemas, do not reuse a read response as a write payload.

In V3, you can address a task only by its Sprinklr task ID, passed in the id query parameter.

?id=6a1437f751d06294d5c8773e                                  # single
?id=6a1437f751d06294d5c8773e,6a15305cad837f75fc5ac662         # bulk

Task IDs are 24-character hex ObjectId strings. Store the id returned in the POST response.

All API calls are sent to the production endpoint:

https://api3.sprinklr.com/{env}/api/v3

So the task resource in production is:

https://api3.sprinklr.com/{env}/api/v3/task

Replace {env} with your assigned environment identifier. The V3 specification enumerates: prod, prod0, prod2, and so on. See APIs | Sprinklr Developer Portal for the current environment list.

Do not hard-code the host name. Make the base URL a single configuration value so promotion between environments is a config change, not a code change.

All Task API calls are authenticated with OAuth 2.0. See API Overview for portal registration, API key and secret generation, and the Authorize flow.

The V3 specification declares two security schemes, both applied to every operation:

POST /api/v3/task

Use this endpoint to create a task for an existing entity.

curl --location 'https://api3.sprinklr.com/{env}/api/v3/task' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "assignment": {
        "assigneeId": "600005371",
        "assigneeType": "USER"
    },
    "taskType": "Working task",
    "taskStatus": "AVAILABLE",
    "title": "Review creative brief",
    "description": "Review creative brief before approval",
    "assetId": "{{assetId}}",
    "assetType": "MESSAGE",
    "dueDate": 1779820200000,
    "customProperties": {},
    "queueIds": ["100623"]
}'

A successful request returns 201 Created and the newly created task. The data property contains a single task object.

{
"data": {
    "id": "6a15305cad837f75fc5ac662",
    "assignment": {},
    "taskType": "Working task",
    "taskStatus": "AVAILABLE",
    "title": "Review creative brief",
    "description": "Review the creative brief before production starts.",
    "assetId": "{{assetId}}",
    "assetType": "MESSAGE",
    "dueDate": 1779820200000,
    "customProperties": {
        "spr_task_status": ["AVAILABLE"],
        "spr_task_type": ["Working task"]
    },
    "inactive": false,
    "queueDetails": [],
    "createdTime": 1779773532036,
    "modifiedTime": 1779773532036,
    "externalCases": []
},
"errors": []
}

Notes:

• POST responses return a single object in data. GET responses return an array in data. Your client must handle both formats.
• Sprinklr automatically maps taskStatus and taskType to the reserved custom properties spr_task_status and spr_task_type. Do not populate these keys directly. Set taskStatus and taskType, and allow the platform to maintain the mirror fields.

attachment supports multiple attachment schemas. The V3 specification models it as a oneOf across 40+ attachment schemas, discriminated by the type property — IMAGE, VIDEO, LINK, DOCUMENT, AUDIO, CAROUSEL, and others. type is required on every variant.

Fields commonly used on a task attachment (from ImageAttachment / DocumentAttachment):

"attachment": {
    "type": "IMAGE",
    "url": "https://cdn.example.com/media/task-brief.jpg",
    "title": "Creative brief v2",
    "previewUrl": "https://cdn.example.com/media/task-brief_p.jpg"
}

PUT /api/v3/task?id={taskId} — TaskApiV3_updateTask

Use this endpoint to replace the entire task. V2 full-update semantics remain unchanged. The API removes any fields that you omit from the request.

curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/task?id={{taskId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "assignment": {
        "assigneeId": "{{assigneeId}}",
        "assigneeType": "USER"
    },
    "taskType": "Working task",
    "taskStatus": "AVAILABLE",
    "title": "Review updated creative brief",
    "description": "Review the updated creative brief before production starts.",
    "assetId": "{{assetId}}",
    "assetType": "MESSAGE",
    "dueDate": 1779820200000,
    "customProperties": {},
    "queueIds": [
        "{{queueId}}"
    ]
}'

A successful request returns 200 OK and the updated task. For information about the response parameters, see Response field reference — Task.

The example above omits customProperties, subscribers, queueIds, and parentTaskId. Under replace semantics those are unset. Before issuing a PUT:

1. GET the current task.
2. Merge your changes into the retrieved document.
3. Map queueDetails[].queueId back to queueIds — the read and write shapes differ (§1.1).
4. PUT the merged result back.

If you only intend to change a few fields, use PATCH (§4.3) instead. PATCH eliminates the need for a read-modify-write cycle when you update only a subset of fields.

PATCH /api/v3/task?id={taskId}

Use the endpoint to update specific task fields without replacing the entire task. Only the fields included in the request body are updated. Supports bulk partial updates through a comma-separated ?id=.

Note: op values come from the shared Operation enum.

curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/task?id={{taskId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "updateFields": [
        {
        "op": "UPDATE",
        "fieldName": "title",
        "value": "Reviewed creative brief"
        },
        {
        "op": "UPDATE",
        "fieldName": "taskStatus",
        "value": "IN_PROGRESS"
        }
    ]
}'

Note: PUT and PATCH take different body schemas. You cannot reuse one payload for both methods.

DELETE /api/v3/task?id={taskId1},{taskId2}

Use this endpoint to delete one or more tasks by ID.

# Single delete
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/task?id={{taskId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

# Bulk delete
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/task?id={{taskId1}},{{taskId2}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

Note: Do not confuse deletion with the inactive flag on the Task object. inactive: true marks a task as inactive but is not the same as removing it. Verify the supported soft-delete behaviour before implementing either approach.

GET /api/v3/task?id=taskId1,taskId2 — TaskApiV3_getTasks

Use this endpoint to retrieve one or more tasks in a single request trip.

# Single fetch
curl --location 'https://api3.sprinklr.com/{env}/api/v3/task?id=6a1437f751d06294d5c8773e' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

# Bulk fetch
curl --location 'https://api3.sprinklr.com/{env}/api/v3/task?id=6a1437f751d06294d5c8773e,6a15305cad837f75fc5ac662' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

A successful request returns 200 OK and the requested task data. The response contains an array of task objects, including when you request a single task.

{
    "data": [
        {
            "id": "6a1437f751d06294d5c8773e",
            "assignment": {},
            "taskType": "Working task",
            "taskStatus": "AVAILABLE",
            "title": "Task",
            "assetId": "INSTAGRAM_37_18442753900191622_ACCOUNT_600037626_1779440700000_2026_05",
            "assetType": "MESSAGE",
            "dueDate": 1779820200000,
            "customProperties": {
                "spr_task_status": ["Available"],
                "spr_task_type": ["Working task"],
                "_c_64e462458f027e15378d09c5": ["5"],
                "_c_64c38d050e8ea978f3f12b82": ["v12"],
                "_c_61542d4bfd7c10301568d465": ["Not Authenticated"],
                "_c_65169c803884d32abe7e159c": ["Value1"]
            },
            "inactive": false,
            "queueDetails": [],
            "createdTime": 1779709943117,
            "modifiedTime": 1779709943117,
            "externalCases": []
        }
    ],
    "errors": []
}

Represents third-party cases linked to a Sprinklr universal case.

{
  "data": [ ... ],
  "errors": []
}

id, code, and message are all required on an Error object.

Partial success on bulk operations. For bulk operations, some task IDs can succeed while others fail.

400, 401, 403, and 404 all return the ErrorResponse schema — { "data": null, "errors": [ … ], "metadata": { … } }.

1. Update the base URL to https://api3.sprinklr.com/{env}/api/v3.
2. Move the task ID from the path to ?id= on GET, PUT, and DELETE. This change is straightforward but must be applied throughout your codebase. Search your codebase for api/v2/task/.
3. Change GET response parsing from data to data[0]. If existing code expects an object instead of an array, the migration can fail without obvious errors.
4. Collapse N-call loops into bulk calls. Replace iterative single-task requests with bulk requests where possible.
5. Add partial-success handling. After a bulk call, reconcile returned data against requested IDs and inspect errors.
6. Replace read-modify-write updates with PATCH. Any place you GET a task purely to change one field and PUT it back is a candidate. This also removes the queueDetails → queueIds remapping step.
7. Accept both 200 and 204 from DELETE, and tolerate an empty body.
8. Keep your POST payloads as-is. Create request bodies did not change.

Scenario: an inbound Instagram message needs design work before a reply goes out.

POST /api/v3/task with assetType: "MESSAGE", assetId set to the message ID, assignment.assigneeId set to the designer, and a dueDate. Store the returned id — it is the only key you can use to address the task later.

Scenario: a dashboard holds 40 task IDs and needs title, status, assignee, and due date for each.

GET /api/v3/task?id=id1,id2,id3,…

You can retrieve all 40 tasks in a single request. Under V2 this was 40 sequential GET /api/v2/task/{taskId} calls; This is a primary efficiency improvement in V3.

const ids = taskIds.join(',');
const res = await get(`/api/v3/task?id=${ids}`);

if (res.errors && res.errors.length) {
  handleErrors(res.errors);          // partial success is possible on bulk
}

const byId = new Map(res.data.map(t => [t.id, t]));
const missing = taskIds.filter(id => !byId.has(id));   // reconcile, do not assume 1:1

Scenario: an agent moves a task from AVAILABLE to IN_PROGRESS.

Use PATCH — not PUT:

{ "updateFields": [ { "op": "UPDATE", "fieldName": "taskStatus", "value": "IN_PROGRESS" } ] }

Using PUT here would require reconstructing the whole task document, including remapping queueDetails back to queueIds, to change one string.

Scenario: A campaign is delayed by one week and 15 tasks need a new due date.

PATCH /api/v3/task?id=id1,id2,…,id15

{ "updateFields": [ { "op": "UPDATE", "fieldName": "dueDate", "value": 1780425000000 } ] }

The same updateFields set is applied to every listed task. If the tasks need different due dates, issue one call per distinct value.

Scenario: an external PM tool owns task state and pushes the complete record.

Use PUT /api/v3/task?id=… with the full TaskRequest. Because the external tool is authoritative, replace semantics are correct. Still GET first if Sprinklr-side agents can edit custom fields, subscribers, or queues — otherwise the sync erases their work (§4.2).

Scenario: a cancelled campaign leaves 8 orphaned tasks.

DELETE /api/v3/task?id=id1,id2,…,id8

Handle both 200 OK and 204 No Content as successful responses, and re-GET the IDs if you need positive confirmation of removal.

Method selection

• Default to PATCH for edits. Use PUT only when you have the complete authoritative task document.
• A PUT request can remove queue membership, subscribers, and custom properties if you omit them.
• PUT and PATCH take different body schemas. Payloads are not interchangeable.

Identifiers and shapes

• Task IDs are 24-character hex ObjectId strings.
• GET returns data as an array, even for a single ID. POST returns data as an object.
• You write queueIds (Array[String]); you read queueDetails (Array[Queue], with queueId as int64). Do not use a GET response directly in a write operation without remapping fields.
• All timestamps — dueDate, completionDate, createdTime, modifiedTime, assignmentTime — are epoch milliseconds, not seconds and not ISO-8601.

Bulk operations

• Provide multiple IDs as a comma-separated list in the id query parameter. Do not repeat the parameter
• Bulk calls can partially succeed. Reconcile returned data against requested IDs and always inspect errors.
• The specification does not state a maximum number of IDs per call. Verify the supported bulk-request limit before sending large batches.

Custom properties

• customProperties is a map of custom-field ID → Array[String]. Even single-valued fields take a list.
• spr_task_status and spr_task_type are platform-maintained mirrors of taskStatus and taskType. Set the top-level fields, not the mirrors.

Error handling

• Always inspect the errors array even on a 200 response.
• A 403 response typically indicates insufficient permissions.
• Code defensively for 429 and 5xx even though the specification does not declare them for these operations.