# Task API V3 — Developer Guide

- **Applies to:** Sprinklr Task API V3 (`/api/v3/task`)
- **V2 API reference:** [Task | Sprinklr Developer Portal](https://legacy-dev.sprinklr.com/task)


## 1. Overview

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.

| Operation | Method | Path | Bulk |
|  --- | --- | --- | --- |
| Create task | `POST` | `/api/v3/task` | No — one task per call |
| Fetch task(s) | `GET` | `/api/v3/task?id=taskId1,taskId2` | Yes |
| Update task (full replace) | `PUT` | `/api/v3/task?id=taskId1,taskId2` | Yes |
| Update task (partial upsert) | `PATCH` | `/api/v3/task?id=taskId1,taskId2` | Yes — **new in V3** |
| Delete task(s) | `DELETE` | `/api/v3/task?id=taskId1,taskId2` | Yes |


### 1.1 The task data model

| Layer | Object / field | What it holds |
|  --- | --- | --- |
| Identity | `id`, `parentTaskId`, `nextTaskId` | Task identifier and its relationship to other tasks. |
| Descriptive | `title`, `description`, `taskType`, `taskStatus` | Task details, type, and current status. |
| Anchor entity | `assetId`, `assetType` | Entity associated with the task, such as a message or campaign. |
| Assignment | `assignment` | `assigneeId`, `assigneeType`, `assignedById`, `assignmentTime` |
| Scheduling | `dueDate`, `completionDate`, `createdTime`, `modifiedTime` | Timestamps in Epoch-millisecond. |
| Routing | `queueIds` (request) / `queueDetails` (response) | Work queues the task sits in |
| Collaboration | `subscribers`, `attachment` | Task subscribers and attachments. |
| Extensibility | `customProperties` | Custom fields, identified by custom-field ID, in `List<String>`. |
| Lifecycle / integration | `inactive`, `workFlowState`, `externalCases` | Soft-delete marker, workflow execution state, linked third-party cases |


> **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.


| Field | In `TaskRequest` (write) | In `Task` (read) |
|  --- | --- | --- |
| `queueIds` — `Array[String]` | ✅ | — |
| `queueDetails` — `Array[Queue]` | — | ✅ |
| `id`, `createdTime`, `modifiedTime`, `inactive`, `nextTaskId` | — | ✅ (server-assigned) |
| `completionDate`, `workFlowState`, `externalCases` | — | ✅ |
| `assignment`, `taskType`, `taskStatus`, `title`, `description`, `assetId`, `assetType`, `dueDate`, `customProperties`, `attachment`, `subscribers`, `parentTaskId` | ✅ | ✅ |


> **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.


### 1.2 Addressing a task

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.

## 2. Base URLs and environments

**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](https://dev.sprinklr.com/apis) 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.

## 3. Authentication and common headers

All Task API calls are authenticated with OAuth 2.0. See [API Overview](https://dev.sprinklr.com/api-overview) for portal registration, API key and secret generation, and the Authorize flow.

| Header | Value | Purpose | Required on |
|  --- | --- | --- | --- |
| `Authorization` | `Bearer {{accessToken}}` | Authenticates the user with the server | All requests |
| `Key` | `{{apiKey}}` | Authenticates the application with the server | All requests |
| `Content-Type` | `application/json` | Declares the request body media type | `POST`, `PUT`, `PATCH` |
| `Accept` | `application/json` | Declares the acceptable response type | All requests |


## 4. Write operations

### 4.1 Create a task

**`POST /api/v3/task`**

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

#### Request body parameters

| **Parameter** | **Sub Parameter** | **Required** | **Type** | **Description** |
|  --- | --- | --- | --- | --- |
| `assignment` |  | Optional | Object | Assignment details for the task. |
|  | `assigneeId` | Optional | String | Identifier of the user or entity assigned to the task. |
|  | `assigneeType` | Optional | String | Type of assignee.Example: **USER**, **BOT** |
|  | `assignedById` | Optional | Long | Identifier of the user who assigns the task. |
|  | `assignmentTime` | Optional | Long | Time when the user assigns the task, in epoch milliseconds. |
| `taskType` |  | Optional | String | Type of work represented by the task.Example: **Design Task**, **Working task** |
| `taskStatus` |  | Optional | String | Status of the task.Example: **NEW**, **AVAILABLE** |
| `title` |  | Optional | String | Title of the task. |
| `description` |  | Optional | String | Description of the work required for the task. |
| `assetId` |  | Required | String | Identifier of the entity associated with the task. |
| `assetType` |  | Required | String | Type of entity associated with the task.Example: **MESSAGE**, **CAMPAIGN** |
| `dueDate` |  | Optional | Long | Date and time when the task is due, in epoch milliseconds. |
| `customProperties` |  | Optional | Map[String, List[String]] | Custom fields for the task, keyed by custom-field ID. Provide each custom-field value as an array of strings, including single-value fields. |
| `attachment` |  | Optional | Object | Media or document attached to the task. The applicable fields depend on `attachment`.`type`. |
| `subscribers` |  | Optional | Array[Object] | Users or entities that subscribe to task updates. |
|  | `type` | Required within subscriber | String | Type of subscriber. Example: **USER**, **GLOBAL**, **CLIENT** |
|  | `ids` | Optional | Array[String] | Subscriber identifiers. The API interprets each identifier according to `subscribers[]`.`type`. |
| `queueIds` |  | Optional | Array[String] | Identifiers of the work queues to which the task belongs. |
| `parentTaskId` |  | Optional | String | Identifier of the parent task when the task belongs to a task hierarchy. |


#### Request

```bash
curl --location POST '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"]
}'
```

#### Response

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

```json
{
"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.
- 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.



#### 4.1.1 `attachment`

`attachment` supports multiple attachment types, including `IMAGE`, `VIDEO`, `LINK`, `DOCUMENT`, `AUDIO`, `CAROUSEL`, and others. Specify the attachment type in the required `type` property.

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

| **Parameter** | **Required** / **Optional** | **Type** | **Description** |
|  --- | --- | --- | --- |
| `type` | Required when attachment is provided | String | Type of attachment.Example: **IMAGE**, **VIDEO**, **LINK**, **DOCUMENT**, **AUDIO**, and **CAROUSEL**. |
| `url` | Optional | String | URL of the attached media or document. |
| `title` | Optional | String | Title of the attachment. |
| `description` | Optional | String | Description of the attachment. |
| `previewUrl` | Optional | String | URL of the attachment preview. |
| `assetId` | Optional | String | Identifier of the attachment in Sprinklr Digital Asset Management. |
| `mimeType` | Optional | String | MIME type of the attachment. |
| `alternateText` | Optional | String | Alternative text that describes the attachment. |
| `sizeInBytes` | Optional | Long | Size of the attachment in bytes. |


```json
"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"
}
```

### 4.2 Update a task — full update

**`PUT /api/v3/task?id={taskId}`**

Use this endpoint to replace the entire task. The API removes any fields that you omit from the request.

#### Query parameters

| Parameter | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| `id` | String | Required | Identifier of the task to update, or a comma-separated list of task identifiers for a bulk update. | `6a1437f751d06294d5c8773e` |


#### Request

```bash
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}}"
    ]
}'
```

#### Response

A successful request returns **200 OK** and the updated task. For information about the response parameters, see [Response field reference — `Task`](#response-field-reference--task).

#### ⚠️ `PUT` replaces — it does not merge

The example above omits `customProperties`, `subscribers`, `queueIds`, and `parentTaskId`. A `PUT` request replaces the existing task, so omitted fields are unset. Before sending a `PUT` request:

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](#11-the-task-data-model)).
4. `PUT` the merged result back.


If you only intend to change a few fields, use `PATCH` ([§4.3](#43-update-a-task--partial-update)) instead. Use `PATCH` to update only the fields you want to change.

### 4.3 Update a task — partial update

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

Use this endpoint to update selected task fields without replacing the entire task. Only fields included in the request body are updated. To update multiple tasks in one request, provide comma-separated task IDs in the `id` query parameter.

#### Query parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `id` | String | Required | Identifier of the task to update, or a comma-separated list of task identifiers for a bulk partial update. |


#### Request body parameters

| **Parameter** | **Required** | **Type** | **Description** |
|  --- | --- | --- | --- |
| `updateFields` | Yes | Array[Object] | Field update operations to apply to each identified task. |
| `updateFields[].fieldName` | Yes | String | Name of the task field to update. Examples: `title`, `taskStatus`, `dueDate`. |
| `updateFields[].value` | Yes | Any | New value for the field. Use the data type defined for the selected task field. |
| `updateFields[].op` | Yes | String | Operation to apply to the field. |


> **Note**: `op` values come from the shared `Operation` enum.


#### Request

```bash
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"
        }
    ]
}'
```

### 4.4 Method comparison — when to use which

|  | `POST` | `PUT` | `PATCH` |
|  --- | --- | --- | --- |
| Purpose | Create a task | Replace the full task document | Upsert selected fields |
| Addressing | None — server assigns the ID | `?id=` | `?id=` |
| Bulk | No | Yes, via comma-separated `?id=` | Yes, via comma-separated `?id=` |
| Unspecified fields | N/A | **Unset** | **Preserved** |
| Safe for incremental sync | — | No, without read-modify-write | Yes |
| Available in V2 | Yes | Yes (path-based) | **No — new in V3** |


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


### 4.5 Delete tasks

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

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

#### Query parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `id` | String | Required | Identifier of the task to delete, or a comma-separated list of task identifiers for a bulk delete. |


#### Request

```bash
# 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**: The `inactive` flag is different from deleting a task. Setting `inactive` to `true` marks the task as inactive but does not delete it.


## 5. Read operations

### 5.1 `GET /api/v3/task` — Fetch tasks by ID

**`GET /api/v3/task?id=taskId1,taskId2`**

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

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `id` | String | Required | Comma-separated list of task IDs. |


```bash
# Single fetch
curl --location GET '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 GET 'https://api3.sprinklr.com/{env}/api/v3/task?id=6a1437f751d06294d5c8773e,6a15305cad837f75fc5ac662' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

#### Response

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.

```json
{
    "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": []
}
```

#### Response field reference — `Task`

| **Parameter** | **Type** | **Description** |
|  --- | --- | --- |
| `id` | String | Unique identifier of the task. |
| `assignment` | Object | Assignment details for the task. |
| `assignment.assigneeId` | String | Identifier of the assigned user or entity. |
| `assignment.assigneeType` | String | Type of assignee. |
| `assignment.assignedById` | Long | Identifier of the user who assigned the task. |
| `assignment.assignmentTime` | Long | Time when the user assigned the task, in epoch milliseconds. |
| `taskType` | String | Type of work represented by the task. |
| `taskStatus` | String | Current status of the task. |
| `title` | String | Title of the task. |
| `description` | String | Description of the work required for the task. |
| `assetId` | String | Identifier of the entity for which the task was created. |
| `assetType` | String | Type of entity for which the task was created. |
| `parentTaskId` | String | Identifier of the parent task. |
| `nextTaskId` | String | Identifier of the next task in the task sequence. |
| `completionDate` | Long | Date and time when the task was completed, in epoch milliseconds. |
| `dueDate` | Long | Date and time when the task is due, in epoch milliseconds. |
| `customProperties` | Map[String, List[String]] | Custom fields returned for the task. Each custom-field ID maps to an array of strings. |
| `inactive` | Boolean | Specifies whether the task is inactive. |
| `attachment` | Object | Media or document attached to the task. |
| `subscribers` | Array[Object] | Users or entities that subscribe to task updates. |
| `subscribers[].type` | String | Type of subscriber. |
| `subscribers[].ids` | Array[String] | Subscriber identifiers. |
| `queueDetails` | Array[Object] | Work queues to which the task belongs. |
| `queueDetails[].queueId` | Long | Identifier of the work queue. |
| `queueDetails[].assignmentTime` | Long | Time when the task entered the queue, in epoch milliseconds. |
| `createdTime` | Long | Time when Sprinklr created the task, in epoch milliseconds. |
| `modifiedTime` | Long | Time when Sprinklr last modified the task, in epoch milliseconds. |
| `workFlowState` | Object | Current workflow execution state for the task. |
| `workFlowState.executionTokenId` | String | Identifier of the workflow execution token. |
| `workFlowState.processVariables` | Object | Variables associated with the workflow execution. |
| `externalCases` | Array[Object] | Third-party cases linked to the task. |


### 5.2 `externalCases`

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

| **Parameter** | **Type** | **Description** |
|  --- | --- | --- |
| `id` | String | Unique identifier of the case in the third-party system. |
| `caseNumber` | String | Case number assigned by the third-party system. |
| `channelType` | String | Third-party platform that manages the case. |
| `permalink` | String | URL of the case in the third-party platform. |
| `createdTime` | Long | Time when the third-party system created the case, in epoch milliseconds. |
| `modifiedTime` | Long | Time when the third-party system last modified the case, in epoch milliseconds. |
| `clientId` | Long | Identifier of the Sprinklr client linked to the case. |
| `subDomain` | String | Subdomain associated with the third-party case. |
| `additional` | Map[String, String] | Additional attributes returned for the third-party case. |


## 6. Response format and status codes

### 6.1 The V3 envelope

Every V3 Task endpoint returns the same envelope. All responses are wrapped in `{ "data": { … }, "errors": [] }`.

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

| Field | Type | Description |
|  --- | --- | --- |
| `data` | Object or Array | The task (`POST`) or tasks (`GET`) affected. `null` on an error response. |
| `errors` | Array[Error] | Error objects — empty when there are no errors |
| `errors[].id` | String | 24-character hex ObjectId |
| `errors[].code` | Integer | Error code |
| `errors[].message` | String | Dotted error key, for example `account.not.found` |


`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.

### 6.2 Response codes

| HTTP code | Declared on | Scenario |
|  --- | --- | --- |
| `200 OK` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | Success |
| `204 No Content` | `DELETE` | Delete succeeded, no response body |
| `400 Bad Request` | All | Malformed request — for example a missing or malformed `id`, or an invalid body |
| `401 Unauthorized` | All | Missing or invalid authentication |
| `403 Forbidden` | All | Insufficient permissions |
| `404 Not Found` | All | Task not found |


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

## 7. Migration from V2 to V3

### 7.1 Endpoint mapping

| V2 | V3 | Change |
|  --- | --- | --- |
| [`POST /api/v2/task`](https://dev.sprinklr.com/create-task) | `POST /api/v3/task` | Version segment only. Body unchanged. |
| [`GET /api/v2/task/{taskId}`](https://dev.sprinklr.com/read-task) | `GET /api/v3/task?id={taskId}` | Task IDs are passed as query parameters and can include multiple IDs. Response `data` becomes an array. |
| [`PUT /api/v2/task/{taskId}`](https://dev.sprinklr.com/update-task) | `PUT /api/v3/task?id={taskId}` | Task IDs are passed as query parameters and can include multiple IDs. Bulk added. Replace semantics retained. |
| *(none)* | `PATCH /api/v3/task?id={taskId}` | **New.** Partial upsert. |
| [`DELETE /api/v2/task/{taskId}`](https://dev.sprinklr.com/delete-task) | `DELETE /api/v3/task?id={taskId}` | Task IDs are passed as query parameters and can include multiple IDs. |


### 7.2 What changed, and what did not

| Aspect | API V2 | API V3 | Impact |
|  --- | --- | --- | --- |
| Task addressing | Path segment `/task/{taskId}` | Query parameter `?id=` | Update all code that constructs task URLs. |
| Bulk operations | Not supported — one task per call | `GET`, `PUT`, `PATCH`, `DELETE` accept comma-separated IDs | You can replace multiple calls with a single bulk request. |
| Partial update | Not available | `PATCH` with `updateFields` | Use `PATCH` to update selected fields without retrieving and resubmitting the complete task. |
| `GET` response `data` | Single object | **Array** | Read `data[0]`, not `data` |
| Response envelope | `{ "data": …, "errors": [] }` | `{ "data": …, "errors": [] }` | Unchanged |
| Create request body | `TaskRequest` fields | Identical fields | No change needed. |
| Delete response | `204 No Content` | `204` per acceptance criteria; `200` per specification | Accept both — see [§4.5](#45-delete-tasks) |
| Partial success | N/A (single-entity calls) | Possible on bulk calls | Inspect `errors` on `200` |


### 7.3 Migration steps

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`.
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.


## 8. Use cases

### 8.1 Create a task on an inbound message

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

Send a `POST /api/v3/task` request with `assetType` set to `MESSAGE`, `assetId` set to the message ID, `assignment.assigneeId` set to the designer's ID, and the required `dueDate`. Store the returned task id for subsequent requests.

### 8.2 Hydrate a production dashboard

**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.

```javascript
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
```

### 8.3 Advance a task's status

**Scenario:** An agent moves a task from `AVAILABLE` to `IN_PROGRESS`.

Use `PATCH` — not `PUT`:

```json
{ "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.

### 8.4 Bulk-reschedule a set of tasks

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

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

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

Using `PUT` to change a single field requires sending the complete task definition and mapping `queueDetails` back to `queueIds`.

### 8.5 Full sync from an external project-management tool

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

Use `PUT /api/v3/task?id=` with the complete task definition. If users can update custom fields, subscribers, or queues in Sprinklr, retrieve the current task before sending the `PUT` request and preserve those changes in the request body. ([§4.2](#42-update-a-task--full-update)).

### 8.6 Clean up a batch of cancelled tasks

**Scenario:** A cancelled campaign leaves 8 orphaned tasks.

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

Treat both `200 OK` and `204 No Content` as successful responses. To confirm that the tasks were removed, retrieve the task IDs again.

## 9. Caveats and best practices

**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**.
- Use `queueIds` in write requests and `queueDetails` in responses. When using data from a `GET` response in a write request, map each `queueDetails.queueId` value to `queueIds`.ß
- All timestamps — `dueDate`, `completionDate`, `createdTime`, `modifiedTime`, `assignmentTime` — are **epoch milliseconds**.


**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`.


**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.
- A `403` response typically indicates insufficient permissions.