# Participant API V3 — Developer Guide

- **Applies to:** Sprinklr Account Participant API V3 (`/api/v3/account/participants`)
- **V2 API reference:** [Participant API | Sprinklr Developer Portal](https://dev.sprinklr.com/participant-api)


## 1. Overview

Using the participant APIs, you can create a participant and configure a primary participant for participating in the **omnichannel handover protocol**. In V2, the create operation is described as setting up a participant ID for a third-party bot, and the account-participant update is used to link that participant with a social account on Sprinklr.

> Related knowledge base article: [Omnichannel Handover Protocol.](https://www.sprinklr.com/help/articles/api/omnichannel-handover-protocol/64832193723d925979db8cd4)


Participant V3 exposes full CRUD on a **single resource path**, differentiated by HTTP method:

| Operation | Method | Path |
|  --- | --- | --- |
| Create participant | `POST` | `/api/v3/account/participants` |
| Fetch participant(s) | `GET` | `/api/v3/account/participants?id=` or `?accountId=` |
| Update participant (full replace) | `PUT` | `/api/v3/account/participants?id=` |
| Patch participant associations | `PATCH` | `/api/v3/account/participants?id=` |
| Delete participant(s) | `DELETE` | `/api/v3/account/participants?id=` |


### 1.1 The participant data model

| Object | Fields | Purpose |
|  --- | --- | --- |
| `Participant` | `id`, `name`, `imageUrl`, `callbackUrl` | The participant record itself |
| `AccountParticipantPatchRequestDTO` | `accountId`, `accountLinkAction`, `primaryAction` | The association between a participant and a social account |
| `AccountParticipantFetchResponseDTO` | `participant`, `participantIds` | Read result — a single participant, or a list of participant IDs |


A participant is created first; its **association with a social account** (link/unlink, primary/not-primary) is then managed separately through `PATCH`.

### 1.2 Addressing a participant

A participant is addressed by its Sprinklr participant ID in the `id` query parameter, for example `6a671fbad316e45725dac06c`. `GET` and `DELETE` accept **comma-separated** IDs for bulk operations; `PUT` and `PATCH` act on a single ID.

## 2. Base URLs and environments

**All API calls are sent to the production endpoint:**

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

So the participant resource is:

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

Replace `{env}` with your assigned environment identifier (`prod0`, `prod2`, `prod11`, and so on — see [APIs | Sprinklr Developer Portal](https://dev.sprinklr.com/apis) for the environment list).

## 3. Authentication and common headers

All Participant API calls are authenticated with OAuth 2.0. See [Developer Tools in Sprinklr](https://www.sprinklr.com/help/articles/developer-tools/developer-tools-in-sprinklr/692e8b39f0afa271d18a5929) for API key and secret generation, and the Authorize flow on the developer portal.

| Header | Value | Purpose | Required on |
|  --- | --- | --- | --- |
| `Authorization` | `******` | 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 participant

**`POST /api/v3/account/participants`**

Creates a participant that can take part in the omnichannel handover protocol — for example, a third-party bot.

#### Request body — `Participant`

| Parameter | Required | Type | Description |
|  --- | --- | --- | --- |
| `id` | Optional | String | Participant id. Server-assigned on create. |
| `name` | **Required** | String | Name of the participant |
| `imageUrl` | **Required** | String | Image URL of the participant |
| `callbackUrl` | **Required** | String | Callback URL of the participant |


#### Request

```bash
curl --location 'https://api3.sprinklr.com/{env}/api/v3/account/participants' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "name": "Cricket Club & Programmes1",
    "imageUrl": "https://s3.ap-south-1.amazonaws.com/qa4-uploads-container/400002/ACCOUNT/IMAGE/0EA329067F374758DEA0BF2458155C7D"
}'
```

#### Response

`200 Success`, body `AccountParticipantFetchResponseDTO`.

**Response** *(illustrative example, generated from the documented schema)*

```json
{
  "participant": {
    "id": "6a671fbad316e45725dac06c",
    "name": "Cricket Club & Programmes1",
    "imageUrl": "https://s3.ap-south-1.amazonaws.com/qa4-uploads-container/400002/ACCOUNT/IMAGE/0EA329067F374758DEA0BF2458155C7D",
    "callbackUrl": "https://example.com/participant/callback"
  }
}
```

Capture the returned `participant.id`. Every later call addresses the participant by that ID.

### 4.2 Update a participant — full update

**`PUT /api/v3/account/participants?id={participantId}`**

Replaces the participant record with the supplied document.

#### Query parameters

| Parameter | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| `id` | String | Optional in the specification; required in practice | Participant id | `6a671fbad316e45725dac06c` |


#### Request body — `Participant`

Same schema as [§4.1](#41-create-a-participant).

#### Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=6a671fbad316e45725dac06c' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
  "name": "Cricket Club & Programmes Updated",
  "imageUrl": "https://s3.ap-south-1.amazonaws.com/qa4-uploads-container/400002/ACCOUNT/IMAGE/0EA329067F374758DEA0BF2458155C7D"
}'
```

#### Response

`200 Success`, body type `string` per the specification (not the JSON envelope returned by `POST`).

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

`PUT` takes the whole `Participant` document. Any field you omit — `callbackUrl`, for instance, as in the sample above — is at risk of being cleared. Before issuing a `PUT`:

1. `GET` the current participant.
2. Merge your changes into the retrieved document.
3. `PUT` the merged result back.


If you only need to change the **account association** (link/unlink, primary), use `PATCH` ([§4.3](#43-patch-participant-associations)) — that is a different schema entirely and does not touch `name`, `imageUrl`, or `callbackUrl`.

### 4.3 Patch participant associations

**`PATCH /api/v3/account/participants?id={participantId}`**

Partial update: link or unlink a participant to an account, and/or set or unset it as the primary participant on that account.

> **Dev note:** make this call **immediately after creating the participant**, to link that participant with the social account on Sprinklr.


#### Query Parameters

| Parameter | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| `id` | String | Optional in the specification; required in practice | Participant id | `6a671fbad316e45725dac06c` |


#### Request Body — `AccountParticipantPatchRequestDTO`

| Parameter | Required | Type | Description | Allowed values |
|  --- | --- | --- | --- | --- |
| `accountId` | Optional | Integer (`int64`) | Account id for link or primary operations | e.g. `66000000` |
| `accountLinkAction` | Optional | String | Link participant to account | `SET`, `UNSET` |
| `primaryAction` | Optional | String | Primary participant on account | `SET`, `UNSET` |


#### Request

```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=6a671fbad316e45725dac06c' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "accountId": "66000000",
    "accountLinkAction": "SET"
}'
```

#### Response

`200 Success`, body type `string`.

#### Choosing the right action

| Intent | Body |
|  --- | --- |
| Link the participant to an account | `{"accountId": <id>, "accountLinkAction": "SET"}` |
| Unlink the participant from an account | `{"accountId": <id>, "accountLinkAction": "UNSET"}` |
| Make the participant primary on an account | `{"accountId": <id>, "primaryAction": "SET"}` |
| Remove primary status | `{"accountId": <id>, "primaryAction": "UNSET"}` |
| Link and set primary in one call | `{"accountId": <id>, "accountLinkAction": "SET", "primaryAction": "SET"}` |


### 4.4 Delete participant(s)

**`DELETE /api/v3/account/participants?id={participantId}`**

Deletes one or more participants. Supports bulk deletion through comma-separated IDs.

#### Query parameters

| Parameter | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| `id` | String | Optional in the specification; required in practice | Participant id(s), comma-separated | `6a60813b6a74f25cd1467718` |


#### Request

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=6a60813b6a74f25cd1467718' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

```bash
# Bulk delete
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=6a60813b6a74f25cd1467718,6a671fbad316e45725dac06c' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

#### Response

`200 Success`, body type `string`.

### 4.5 Method comparison — when to use which

|  | `POST` | `PUT` | `PATCH` | `DELETE` |
|  --- | --- | --- | --- | --- |
| Purpose | Create a participant | Replace the participant record | Change account association only | Remove participant(s) |
| Addressing | None — identity is server-assigned | `?id=` | `?id=` | `?id=` (comma-separated) |
| Body schema | `Participant` | `Participant` | `AccountParticipantPatchRequestDTO` | None |
| Unspecified fields | N/A | **Replaced/cleared** | **Preserved** | N/A |
| Bulk | No | No | No | **Yes** |
| Response body | `AccountParticipantFetchResponseDTO` | `string` | `string` | `string` |


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

## 5. Read operations

### 5.1 `GET /api/v3/account/participants` — Fetch participant(s)

This is a **dual-mode** endpoint: fetch a participant by its own ID, or list the participant IDs attached to an account.

| Parameter | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| `id` | String | Optional | Participant id(s), comma-separated | `6a671fbad316e45725dac06c` |
| `accountId` | String | Optional | Account id to list participants for | `66000000` |


#### Mode 1 — Fetch by participant id

```bash
curl --location 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=6a671fbad316e45725dac06c' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

```bash
# Multiple IDs in one call
curl --location 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=6a671fbad316e45725dac06c,6a60813b6a74f25cd1467718' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

#### Mode 2 — List participants on an account

```bash
curl --location 'https://api3.sprinklr.com/{env}/api/v3/account/participants?accountId=66000000' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

#### Response

`200 Success`, body: **array of** `AccountParticipantFetchResponseDTO`.

| Field | Type | Description |
|  --- | --- | --- |
| `participant` | Object (`Participant`) | Participant details when fetched by participant id |
| `participantIds` | Array[String] | Participant ids when fetched by account id |


**Response — fetch by `id`** *(illustrative example, generated from the documented schema)*

```json
[
  {
    "participant": {
      "id": "6a671fbad316e45725dac06c",
      "name": "Cricket Club & Programmes1",
      "imageUrl": "https://s3.ap-south-1.amazonaws.com/qa4-uploads-container/400002/ACCOUNT/IMAGE/0EA329067F374758DEA0BF2458155C7D",
      "callbackUrl": "https://example.com/participant/callback"
    }
  }
]
```

**Response — fetch by `accountId`** *(illustrative example, generated from the documented schema)*

```json
[
  {
    "participantIds": [
      "6a671fbad316e45725dac06c",
      "6a60813b6a74f25cd1467718"
    ]
  }
]
```

Fetching by `accountId` returns **IDs only**. To hydrate them, follow up with a comma-separated `?id=` call rather than one call per ID.

> **Parameter hygiene.** Both `id` and `accountId` are declared optional, so a call with neither is syntactically valid but has no defined behavior. Always send exactly one of the two.


## 6. Response format and status codes

### 6.1 Response bodies

Unlike most V3 read endpoints, the participant operations do **not** all return the standard `data`/`errors`/`metadata` envelope in `sprinklr-v3.yaml`:

| Operation | Declared `200` schema |
|  --- | --- |
| `GET` | `array` of `AccountParticipantFetchResponseDTO` |
| `POST` | `AccountParticipantFetchResponseDTO` |
| `PUT` | `string` |
| `PATCH` | `string` |
| `DELETE` | `string` |


Parse `PUT`, `PATCH`, and `DELETE` responses as plain strings, not JSON objects — or confirm with the API owner that the gateway wraps them in the standard envelope ([§10](#10-questions-for-the-api-owner)).

### 6.2 Response codes

Declared on every participant operation:

| HTTP Code | Scenario | Description |
|  --- | --- | --- |
| `200 OK` | Success | Operation completed successfully |
| `400 Bad Request` | Invalid parameters | Missing required parameters or invalid parameter combinations |
| `401 Unauthorized` | Authentication failed | Invalid or missing `Authorization` token |
| `403 Forbidden` | Insufficient permissions | Caller lacks permission on the account or participant entity |
| `404 Not Found` | Not found | No participant matches the supplied `id`/`accountId` |


`500 Internal Server Error` is not declared on these operations; handle it defensively regardless.

## 7. V2 → V3 migration

### 7.1 Endpoint mapping

| V2 | V3 |
|  --- | --- |
| [Create Participant API](https://dev.sprinklr.com/create-participant-api) | `POST /api/v3/account/participants` |
| [Update Account Participant](https://dev.sprinklr.com/update-account-participant) | `PATCH /api/v3/account/participants?id=` |
| Fetch participant | `GET /api/v3/account/participants?id=` |
| List participants on an account | `GET /api/v3/account/participants?accountId=` |
| Delete participant | `DELETE /api/v3/account/participants?id=` |
| Update participant record | `PUT /api/v3/account/participants?id=` |


The central structural change: V2 exposed participant creation and account-participant update as **separate named endpoints**; V3 consolidates all five operations onto a **single path** differentiated by HTTP method, and splits "update the participant record" (`PUT`) from "update the account association" (`PATCH`).

### 7.2 Migration steps

1. **Update the base URL.** Point at `https://api3.sprinklr.com/{env}/api/v3`.
2. **Collapse your endpoint routing.** All five operations now hit `/account/participant`; select behavior with the HTTP method.
3. **Split your write path.** Route creates to `POST`, participant-record edits to `PUT`, and account link/primary changes to `PATCH`.
4. **Move identifiers to the query string.** Participant IDs travel in `?id=`, not in the path or body.
5. **Adopt the action enums.** Express link and primary changes as `accountLinkAction` / `primaryAction` with `SET` or `UNSET`.
6. **Update response parsing.** `GET` returns an **array**; `PUT`/`PATCH`/`DELETE` return a `string`.
7. **Preserve the create → link ordering.** Call `PATCH` immediately after `POST`, as in V2.


## 8. Supported enums

| Field | Allowed values | Meaning |
|  --- | --- | --- |
| `accountLinkAction` | `SET` | Link the participant to the account |
|  | `UNSET` | Unlink the participant from the account |
| `primaryAction` | `SET` | Mark the participant as primary on the account |
|  | `UNSET` | Remove primary status |


Values are uppercase.

## 9. Use cases

### 9.1 Onboard a third-party bot as a participant

**Scenario:** you are integrating an external bot into the omnichannel handover protocol.

1. `POST /api/v3/account/participants` with `name`, `imageUrl`, and `callbackUrl`. Capture `participant.id`.
2. **Immediately** `PATCH /api/v3/account/participants?id={participantId}` with `{"accountId": <accountId>, "accountLinkAction": "SET"}` to link it to the social account.


Skipping step 2 leaves an orphan participant that no account can hand over to.

### 9.2 Promote a participant to primary on an account

```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=6a671fbad316e45725dac06c' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--data '{"accountId": 66000000, "primaryAction": "SET"}'
```

### 9.3 Audit which participants are attached to an account

1. `GET /api/v3/account/participants?accountId=66000000` → returns `participantIds`.
2. `GET /api/v3/account/participants?id=id1,id2,id3` → hydrates names, images, and callback URLs in a single call.


### 9.4 Rebrand a participant

Fetch first, then replace:

1. `GET /api/v3/account/participants?id=6a671fbad316e45725dac06c`
2. Change `name` and `imageUrl` on the retrieved document, keeping `callbackUrl`.
3. `PUT /api/v3/account/participants?id=6a671fbad316e45725dac06c` with the merged document.


Do not `PUT` a partial body — see [§4.2](#42-update-a-participant--full-update).

### 9.5 Decommission a bot

1. `PATCH` with `{"accountId": <id>, "primaryAction": "UNSET"}`, then `{"accountId": <id>, "accountLinkAction": "UNSET"}` for each linked account.
2. `DELETE /api/v3/account/participants?id={participantId}`.


Unlink before deleting so no account is left pointing at a removed primary participant. Whether `DELETE` cascades the unlink automatically is not documented — see [§10](#10-questions-for-the-api-owner).

### 9.6 Clean up test participants in bulk

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/account/participants?id=id1,id2,id3,id4' \
--header 'Authorization: ******' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

`DELETE` is the only participant operation with bulk support. `PUT` and `PATCH` act on a single `id`.