# Account API V3 — Developer Guide

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


## 1. Overview

An **account** refers to the brand’s social media account that has been successfully added to Sprinklr. Once added, you can **view, edit, update, delete, or deactivate** the account.

📖 Related Knowledge Base Article: [Account](https://www.sprinklr.com/help/categories/account/64588f3a72241235fc62be8a)

## 2. API Endpoints

| **Operation** | **Method** | **Path** |
|  --- | --- | --- |
| Fetch Account (by Id) | GET | `/api/v3/account?id={id}` |
| Fully Update Account | PUT | `/api/v3/account?id={id}` |
| Partially Update Account | PATCH | `/api/v3/account?id={id}` |
| Delete Account | DELETE | `/api/v3/account?id={id}&clientId={clientId}` |


## 3. Base URL

All API calls are sent to:

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

So the Account resource in production is:

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

Replace `{env}` with your assigned environment identifier (`prod0`, `prod2`, `prod11`, etc.).

## 4. Authentication & Headers

| **Header** | **Value** | **Purpose** |
|  --- | --- | --- |
| Authorization | Bearer {token} | Authenticates the user with the server |
| api-key | {api-key} | Authenticates the application with the server |
| Content-Type | application/json | Declares request body media type |
| Accept | application/json | Declares acceptable response type |


## 5. Account Operations

### 5.1 Fetch Account

**`GET /api/v3/account?id={id}`**

Retrieves account details using its unique ID.

## Query Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| id | Required | The unique ID of the account added in Sprinklr. | String |


## Steps to Extract Account ID from Sprinklr UI

1. Navigate to **All Settings**.
2. Open the **Accounts** page.
3. Locate the account you want.
4. Click the **three‑dot icon** next to the account name.
5. Select **Details** from the dropdown. A third‑pane window opens.
6. In the window, click the **copy URL icon** at the top right.
7. Paste the copied URL into any encoder/decoder tool.
8. The account ID will appear in the decoded URL.


**Example:**
If the decoded URL contains `/ACCOUNT/100426226/OVERVIEW`, then the account ID is **100426226**.

## Example — Request

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/account?id=66000053' \
--header 'Authorization: {Enter your Access Token}' \
--header 'Key: {Enter your API KEY}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
```

### 5.2 Fully Update Account

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

Replaces all custom properties on an account.

## Query Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| id | Required | The unique ID of the account added in Sprinklr. | String |


## Steps to Extract Account ID from Sprinklr UI

1. Navigate to **All Settings**.
2. Open the **Accounts** page.
3. Locate the account you want.
4. Click the **three‑dot icon** next to the account name.
5. Select **Details** from the dropdown. A third‑pane window opens.
6. In the window, click the **copy URL icon** at the top right.
7. Paste the copied URL into any encoder/decoder tool.
8. The account ID will appear in the decoded URL.


**Example:**
If the decoded URL contains `/ACCOUNT/100426226/OVERVIEW`, then the account ID is **100426226**.

## Request Parameters

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| spaceId | Required | Client (space) ID for client‑level custom properties. | long |
| clientCustomProperties | Optional | Client‑level custom properties to replace on the account. Keys are field names; values are string lists. | object (string → array of string) |
| partnerCustomProperties | Optional | Partner‑level custom properties to replace on the account. | object (string → array of string) |


## Example — Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/account?id=66000053' \
--header 'Authorization: {Enter Your Access Token}' \
--header 'Key: {Enter Your API Key}' \
--header 'Content-Type: application/json' \
--data '{
    "spaceId": 66000002,
    "clientCustomProperties": {
        "region": ["US"]
    },
    "partnerCustomProperties": {
        "tier": ["gold"]
    }
}'
```

### 5.3 Partially Update Account

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

Updates account details without overwriting the entire object.  Supports appending/merging custom properties, updating visibility/permissions, or deactivating an account.

## Query Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| id | Required | The unique ID of the account added in Sprinklr. | String |


## Steps to Extract Account ID from Sprinklr UI

1. Navigate to **All Settings**.
2. Open the **Accounts** page.
3. Locate the account you want.
4. Click the **three‑dot icon** next to the account name.
5. Select **Details** from the dropdown. A third‑pane window opens.
6. In the window, click the **copy URL icon** at the top right.
7. Paste the copied URL into any encoder/decoder tool.
8. The account ID will appear in the decoded URL.


**Example:**
If the decoded URL contains `/ACCOUNT/100426226/OVERVIEW`, then the account ID is **100426226**.

## Request Parameters

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| customProperties | Optional | Partial custom properties update. See Object: customProperties. | object |
| visibilityPermissions | Optional | Visibility and/or share permission update. See Object: visibilityPermissions. | object |
| active | Optional | Set to false to deactivate the account. Only false is supported; true returns 400. | boolean |
| deactivationReason | Optional | Reason recorded on deactivation. Defaults to *Deactivated by user using API v3* when omitted and active is false. | string |


### Object: customProperties

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| spaceId | Conditional | Client (space) ID. Required when clientCustomProperties is non‑empty. | long |
| clientCustomProperties | Optional | Client‑level custom properties to append/merge (partial update). | object (string → array of string) |
| partnerCustomProperties | Optional | Partner‑level custom properties to append/merge (partial update). | object (string → array of string) |


### Object: visibilityPermissions

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| visibility | Optional | Visibility to apply. See Object: visibility. | object |
| permissions | Optional | Share permissions to assign. See Object: permissions[] item. | array of objects |


### Object: visibility

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| globallyVisible | Optional | When true, asset is globally visible. | boolean |
| visibilityConfig | Optional | Share targets for visibility. See Object: visibilityConfig[] item. | array of objects |


### Object: visibilityConfig[] item

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| type | Required | Share target type (e.g. USER, GLOBAL, CLIENT). | string |
| ids | Optional | Target IDs for the given type. | array of string |


### Object: permissions[] item

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| type | Required | Share target type (e.g. USER, GLOBAL, CLIENT). | string |
| ids | Optional | Target IDs for the given type. | array of string |


## Example — Request

```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/account?id=66000053' \
--header 'Authorization: {Enter Your Access Token}' \
--header 'Key: {api-key}' \
--header 'Content-Type: application/json' \
--data '{
  "visibilityPermissions": {
    "permissions": [
      {
        "type": "GLOBAL",
        "ids": ["1"]
      }
    ]
  }
}'
```

### 5.4 Delete Account

**`DELETE /api/v3/account?id={id}&clientId={clientId}`**

Removes an account from a specified client (space).

## Query Parameter

| **Parameter** | **Required/Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| id | Required | The unique ID of the account added in Sprinklr. | String |
| clientId | Required | Client/space ID from which to remove the account (positive integer). | String |


## Steps to Extract Account ID from Sprinklr UI

1. Navigate to **All Settings**.
2. Open the **Accounts** page.
3. Locate the account you want.
4. Click the **three‑dot icon** next to the account name.
5. Select **Details** from the dropdown. A third‑pane window opens.
6. In the window, click the **copy URL icon** at the top right.
7. Paste the copied URL into any encoder/decoder tool.
8. The account ID will appear in the decoded URL.


**Example:**
If the decoded URL contains `/ACCOUNT/100426226/OVERVIEW`, then the account ID is **100426226**.

## Example — Request

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/api/v3/account?id=2378712&clientId=108' \
--header 'Authorization: Bearer {Enter Your Access Token}' \
--header 'Key: {api-key}' \
--header 'Accept: application/json'
```

## 6. Response Format & Status Codes

## 6.1 Envelope

```json
{
  "data": Object | Array | String | Boolean,
  "errors": []
}
```

### Example — Response (Fetch Account)

```json
{
  "data": [
    {
      "id": "66000053",
      "type": "SPR_ANNOUNCEMENT",
      "displayName": "Announcement",
      "channelId": "66000000_SPR_ANNOUNCEMENT",
      "owner": 0,
      "channelType": "SPRINKLR",
      "spaceId": 66000002,
      "partnerCustomProperties": {
        "_c_6a1de4ab34f417401396e8cc": ["BMW"],
        "_c_6a1de4e434f417401396f5f9": ["45"]
      },
      "visibility": {
        "globallyVisible": false,
        "visibilityConfig": [
          { "type": "GLOBAL" }
        ]
      },
      "permissions": [
        { "type": "GLOBAL", "ids": ["1", "78", "69"] }
      ],
      "active": true,
      "deactivationReason": "",
      "deleted": false,
      "createdTime": "2024-06-26 12:36:41",
      "modifiedTime": "2025-08-21 06:41:08"
    }
  ],
  "errors": []
}
```

### Response Parameters

| **Parameter** | **Sub‑Param** | **Definition** | **Type** |
|  --- | --- | --- | --- |
| id |  | The unique account ID | Integer |
| type |  | The type of account. Example: TWITTER, LINKEDIN, FBPAGE | String |
| displayName |  | The display name on the social account | String |
| channelId |  | The unique ID of the channel where the account exists | String |
| owner |  | Refers to user ID of the account owner | Integer |
| properties |  | Object defining the different properties (attributes) of the account | Object |
| channelType |  | The respective channel type | String |
| spaceId |  | The client ID related to the account | String |
| clientCustomProperties |  | Workspace‑level custom properties | Object |
| partnerCustomProperties |  | Global‑level custom properties | Object |
| visibility |  | Object containing account sharing (visibility) details | Object |
|  | globallyVisible | Determines whether the account is globally visible or not | Boolean |
|  | shareConfigs | The object containing details of account sharing configuration | Array |
| permissions |  | Array defining the details of different permissions on the account | Array |
| permalink |  | Account URL | URL |
| active |  | Determines whether the account is active or not | Boolean |
| deleted |  | Determines whether the account is deleted or not | Boolean |
| deactivationReason |  | If deactivated, determines the reason of account deactivation | String |
| createdTime |  | The time when the account was created | String |
| modifiedTime |  | The time when the account was last modified | String |


## Array Details for `permissions` and `shareConfigs`

| **Parameter** | **Definition** | **Type** |
|  --- | --- | --- |
| type | The type of permission/shareConfig | String |
| ids | IDs related to the mentioned type | List [String] |


## Notes

- **Fetch Account API** returns a JSON object with `data` and `errors`.
- For **Update, Patch, and Delete APIs**, the response is always:


```http
204 No Content
```

### 6.2 Response codes

| **HTTP Code** | **Scenario** | **Description** |
|  --- | --- | --- |
| 200 OK | Success | Operation executed successfully; resource returned |
| 204 No Content | Success (Update/Delete) | Resource updated or deleted 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 | User lacks permission to perform the operation |
| 404 Not Found | Resource Missing | Business Hours or Holiday List not found |
| 500 Internal Server Error | Server Error | Unexpected server-side error occurred |


## 7. Migration from V2 to V3

The Account APIs have been streamlined in **V3** for consistency and lifecycle control.
Below is a comparison of **V2 vs V3 endpoints and behavior**:

| **Operation** | **V2 Endpoint** | **V3 Endpoint** | **Key Differences** |
|  --- | --- | --- | --- |
| Fetch Account (by Id) | `GET /api/v2/account/{id}`  `GET /api/v2/account/{type}/{id}` | `GET /api/v3/account?id={id}` | V2 supported both path by ID and type+ID; V3 consolidates into query parameter `id`. |
| Fully Replace Custom Properties | `PUT /api/v2/account/update/{id}/customProperties` | `PUT /api/v3/account?id={id}` | V2 used `/update/{id}/customProperties`; V3 uses PUT with query parameter `id`. |
| Append/Merge Custom Properties | `POST /api/v2/account/update/{id}/customProperties` | `PATCH /api/v3/account?id={id}` | V2 used POST for partial updates; V3 uses PATCH with selective fields. |
| Update Visibility Permissions | `PUT /api/v2/account/{id}/visibility-permissions` | `PATCH /api/v3/account?id={id}` with `visibilityPermissions` object | V2 had a dedicated endpoint; V3 consolidates into PATCH with visibilityPermissions. |
| Deactivate Account | `PUT /api/v2/account/{id}/deactivate` | `PATCH /api/v3/account?id={id}` with `active=false` and optional `deactivationReason` | V2 had a separate deactivate endpoint; V3 uses PATCH with `active=false`. |
| Delete Account | *Not supported in V2* | `DELETE /api/v3/account?id={id}&clientId={clientId}` | Delete is newly supported in V3; requires both `id` and `clientId` as query parameters. |