Participant API V3 — Developer Guide

• Applies to: Sprinklr Account Participant API V3 (/api/v3/account/participants)
• V2 API reference: Participant API | Sprinklr Developer Portal

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.

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

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

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.

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 for the environment list).

All Participant API calls are authenticated with OAuth 2.0. See Developer Tools in Sprinklr for API key and secret generation, and the Authorize flow on the developer portal.

POST /api/v3/account/participants

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

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"
}'

200 Success, body AccountParticipantFetchResponseDTO.

Response (illustrative example, generated from the documented schema)

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

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

Replaces the participant record with the supplied document.

Same schema as §4.1.

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"
}'

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

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) — that is a different schema entirely and does not touch name, imageUrl, or callbackUrl.

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.

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"
}'

200 Success, body type string.

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

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

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

# 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'

200 Success, body type string.

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

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

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

# 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'

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

200 Success, body: array of AccountParticipantFetchResponseDTO.

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

[
  {
    "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)

[
  {
    "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.

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

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

Declared on every participant operation:

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

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

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.

Values are uppercase.

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.

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"}'

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.

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.

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.

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.