# Custom Entity API V3 — Developer Guide

- **Applies to:** Sprinklr Reporting Suite APIs V3
- **V2 API reference:** [Reporting Suite APIs | Sprinklr Developer Portal](https://dev.sprinklr.com/reporting-suite)


## 1. Overview

Custom Entities are user‑defined objects created to model business‑specific data such as transactions, appointments, products, loyalty cards, or configuration tables. They allow you to store information unique to your company or industry.

Once defined, you can use the Custom Entity APIs to add new records, modify existing ones, or retrieve data. The data stored in Custom Entities can then be surfaced in the Reporting widget by selecting Data Source = Custom Entity, enabling unified analytics, customer 360° views, and profile enrichment.

**Note**: The Custom Entity feature must be enabled in your instance before you can use these APIs. To enable this feature in your environment, contact your Success Manager.

**Custom Entity V3 exposes the following endpoints under the base path `/api/v3/customEntity`:**

| **Operation** | **Method** | **Path** |
|  --- | --- | --- |
| **Create Custom Entity definition** | `POST` | `/api/v3/customEntity/definition` |
| **Update Custom Entity definition** | `PUT` | `/api/v3/customEntity/definition?id=` |
| **Create Custom Entity field** | `POST` | `/api/v3/customEntity/field` |
| **Update Custom Entity field** | `PUT` | `/api/v3/customEntity/field?id=` |
| **Create Custom Entity record** | `POST` | `/api/v3/customEntity/entity` |
| **Update Custom Entity record (full replace)** | `PUT` | `/api/v3/customEntity/entity?entityType=&entityId=` |
| **Update Custom Entity record (partial)** | `PATCH` | `/api/v3/customEntity/entity?entityType=&entityId=` |
| **Create Custom Entity trigger** | `POST` | `/api/v3/customEntity/trigger` |
| **Update Custom Entity trigger (full replace)** | `PUT` | `/api/v3/customEntity/trigger?id=` |
| **Update Custom Entity trigger (partial)** | `PATCH` | `/api/v3/customEntity/trigger?id=` |
| **Read Custom Entity definition** | `GET` | `/api/v3/customEntity/definition?id=` |
| **Search Custom Entity definitions** | `GET` | `/api/v3/customEntity/definition?pageNumber=` |
| **Read Custom Entity field** | `GET` | `/api/v3/customEntity/field?id=` |
| **Read Custom Entity record** | `GET` | `/api/v3/customEntity/entity?entityType=&entityId=` |
| **Read Custom Entity trigger** | `GET` | `/api/v3/customEntity/trigger?id=` |
| **Delete Custom Entity field** | `DELETE` | `/api/v3/customEntity/field?id=` |
| **Delete Custom Entity record** | `DELETE` | `/api/v3/customEntity/entity?entityType=&entityId=` |
| **Delete Custom Entity trigger** | `DELETE` | `/api/v3/customEntity/trigger?id=` |


## 2. Base URLs and environments

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

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

So the profile resource in production is:

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

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 Profile 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 |


> **Credential hygiene.** Never commit a Bearer token or API key to source control, never paste one into a ticket or chat, and never log the `Authorization` or `Key` header values. Every credential in this guide is a placeholder. If a real token has been exposed, revoke and regenerate it immediately.


## 4. Write operations

### 4.1 Create custom entity definition

**`POST /api/v3/customEntity/definition`**

Creates a new custom entity definition. A custom entity defines a reusable schema for storing business‑specific objects (for example, product catalog items, tickets, or assets). Each definition includes an identifier, name, plural name, and description.

#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | Unique identifier for the custom entity definition.**Example:** `_c_spr_item_1` | String |
| `name` | Required | Display name of the entity definition.**Example:** `Product Catalog` | String |
| `pluralName` | Required | Plural display name for the entity definition.**Example:** `Product Items` | String |
| `description` | Optional | Description of the entity definition’s purpose.**Example:** `Contains products` | String |


#### Request

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/customEntity/definition' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "id": "_c_spr_item_1",
    "name": "Product Catalog",
    "pluralName": "Product Items",
    "description": "Contains products"
}'
```

### 4.2 Update custom entity definition

**`PUT /api/v3/customEntity/definition`**

Updates an existing custom entity definition. This endpoint allows you to modify the identifier, name, plural name, or description of a definition.
**Note:** Updating the `id` will replace the existing identifier with the new one.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | Unique identifier of the custom entity definition to update.**Example:** `_c_spr_item_2` | String |


#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | New identifier for the custom entity definition.**Example:** `_c_spr_item_3` | String |
| `name` | Required | Updated display name of the entity definition.**Example:** `Product Catalog` | String |
| `pluralName` | Required | Updated plural display name.**Example:** `Product Items` | String |
| `description` | Optional | Updated description of the entity definition.**Example:** `Contains products` | String |


#### Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/customEntity/definition?id=_c_spr_item_2' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "id":"_c_spr_item_3",
    "name": "Product Catalog",
    "pluralName": "Product Items",
    "description": "Contains products"
}'
```

### 4.3 Create custom entity field

**`POST /api/v3/customEntity/field`**

Creates a new field within a custom entity definition. Fields define the attributes of the entity (for example, product name, SKU, price, or description). Each field requires an API name, display name, type, and association with a specific entity definition.

#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `apiName` | Required | Unique API identifier for the field.**Example:** `_c_spr_item_2` | String |
| `name` | Required | Display name of the field.**Example:** `Product Catalog` | String |
| `entityDefinitionId` | Required | Identifier of the custom entity definition this field belongs to.**Example:** `_c_spr_item_2` | String |
| `type` | Required | Data type of the field.**Supported Values:** `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `DATETIME` | String |
| `multivalued` | Optional | Whether the field can hold multiple values.**Supported Values:** `true`, `false` | Boolean |


#### Request

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/customEntity/field' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "apiName": "_c_spr_item_2",
    "name": "Product Catalog",
    "entityDefinitionId": "_c_spr_item_2",
    "type": "TEXT",
    "multivalued": "false"
}'
```

### 4.4 Update custom entity field

**`PUT /api/v3/customEntity/field`**

Updates an existing custom entity field. This endpoint allows you to modify the API name, display name, type, or multivalued property of a field.
**Note:** The `id` query parameter identifies the field to update, while the request body provides the new values.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | Unique identifier of the custom entity field to update.**Example:** `_c_spr_item_2__c_spr_item_2` | String |


#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `apiName` | Required | API identifier for the field.**Example:** `_c_spr_item_2` | String |
| `name` | Required | Updated display name of the field.**Example:** `Product Catalog Updated` | String |
| `type` | Required | Data type of the field.**Supported Values:** `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `DATETIME` | String |
| `multivalued` | Optional | Whether the field can hold multiple values.**Supported Values:** `true`, `false` | Boolean |


#### Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/customEntity/field?id=_c_spr_item_2__c_spr_item_2' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "apiName": "_c_spr_item_2",
    "name": "Product Catalog Updated",
    "type": "TEXT",
    "multivalued": "false"
}'
```

### 4.5 Create custom entity record

**`POST /api/v3/customEntity/entity`**

Creates a new record for a custom entity definition. Records represent individual instances of the entity (for example, a single product item, ticket, or weather entry). Each record requires a name, type (entity definition ID), and a set of field values.

#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `name` | Required | Display name of the entity record.**Example:** `Day5` | String |
| `type` | Required | Identifier of the custom entity definition this record belongs to.**Example:** `_c_aditya_delhi_temp` | String |
| `values` | Required | Key‑value pairs representing field values for the record.Keys must match field API names defined in the entity definition.**Example:** `{ "_c_minimum_temp": "28", "_c_maximum_temp": "47" }` | Object |


#### Request

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/customEntity/entity' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "name": "Day5",
    "type": "_c_aditya_delhi_temp",
    "values": {
        "_c_minimum_temp": "28",
        "_c_maximum_temp": "47"
    }
}'
```

### 4.6 Create custom entity record

**`POST /api/v3/customEntity/entity`**

Creates a new record for a custom entity definition. Records represent individual instances of the entity (for example, a customer profile). Each record requires a name, the entity definition ID, and values for the fields defined in that entity.

#### Request body parameters

| **Parameters** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `name` | Optional | The name of the entity.If the name of the entity is not passed, its default value will be the same as the `"id"` in the response. | String |
| `entityId` | Optional | Configured from client‑side and needs to be unique for every entity.It is recommended to pass `entityId`. If not passed, it defaults to the `"id"` in the response.The entity Id is a unique reference. | String |
| `type` | Required | Refers to the custom definition Id.**Example:** `_c_caller_1` | String |
| `values` | Required | The object containing the entity field name and value pairs.Keys must match field API names defined in the entity definition. | Object |


#### Request

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/customEntity/entity' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "name": "Test",
  "type": "_c_caller_1",
  "values": {
    "_c_credit_score": 25,
    "_c_rating": 5,
    "_c_customer_bio": "Works in corporate"
  }
}'
```

### 4.7 Update custom entity record

**`PUT /api/v3/customEntity/entity`**

Updates an existing record for the **Caller v1** custom entity definition. This endpoint allows you to modify the record’s display name and field values. The `entityType` and `entityId` query parameters identify the record to update, while the request body provides the new values.

#### Query parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `entityType` | Required | The type of entity, that is, the unique identifier of the custom entity definition.**Example:** `_c_caller_1` | String |
| `entityId` | Required | The unique identifier for the created custom entity.This is the id you receive in the response of the **Create Custom Entity Record** API.**Example:** `6a984a0d5efb429a8039649b` | String |


#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `name` | Optional | Display name of the entity record.If not passed, defaults to the record’s `id`. | String |
| `type` | Required | Identifier of the custom entity definition this record belongs to.**Example:** `_c_caller_1` | String |
| `values` | Required | Key‑value pairs representing updated field values for the record.Keys must match field API names defined in the entity definition.**Example:** `{ "_c_credit_score": 30, "_c_rating": 7, "_c_customer_bio": "Updated corporate profile" }` | Object |


#### Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/customEntity/entity?entityType=_c_caller_1&entityId=6a984a0d5efb429a8039649b' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "name": "Test Updated",
  "type": "_c_caller_1",
  "values": {
    "_c_credit_score": 30,
    "_c_rating": 7,
    "_c_customer_bio": "Updated corporate profile"
  }
}'
```

### 4.8 Patch custom entity record

**`PATCH /api/v3/customEntity/entity`**

Partially updates an existing record for the custom entity definition. Unlike `PUT`, which replaces the entire record, `PATCH` allows you to update only specific fields. The `entityType` and `entityId` query parameters identify the record to update, while the request body specifies the fields to modify using the `updateFields` array.

#### Query parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `entityType` | Required | The type of entity, that is, the unique identifier of the custom entity definition.**Example:** `_c_caller_1` | String |
| `entityId` | Required | The unique identifier for the created custom entity.This is the id you receive in the response of the **Create Custom Entity Record** API.**Example:** `6a984a0d5efb429a8039649b` | String |


#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `updateFields` | Required | Array of field update operations. Each object must follow the **UpdateField shape** described below. | Array |


#### UpdateFields object parameters

Each object inside `updateFields` must contain the following properties:

| **Property** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `op` | Required | Operation to perform on the field.**Supported Value (for now):** `SET` → replaces the field’s current value with the new one. | String |
| `fieldName` | Required | API name of the field to update.Must match a field defined in the entity definition.**Example:** `_c_credit_score` | String |
| `value` | Required | New value for the specified field.Type must conform to the schema of the field (e.g., number, text). | String / Object |


#### Request

```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/customEntity/entity?entityType=_c_caller_1&entityId=6a984a0d5efb429a8039649b' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "updateFields": [
        {
            "op": "SET",
            "fieldName": "_c_credit_score",
            "value": "40"
        },
        {
            "op": "SET",
            "fieldName": "_c_rating",
            "value": "9"
        },
        {
            "op": "SET",
            "fieldName": "_c_customer_bio",
            "value": "Profile patched with new details"
        }
    ]
}'
```

### 4.9 Create custom entity trigger

**`POST /api/v3/customEntity/trigger`**

Creates a trigger for the custom entity definition. Triggers allow automation logic to run when specific events occur on records (e.g., create, update, delete).

#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `entityType` | Required | Refers to the custom entity type, i.e., the custom entity definition.**Example:** `_c_caller_1` | String |
| `type` | Required | Refers to the type of trigger.Supported types:- `SCRIPT`: the action includes a script.- `RULE`: the action includes the rule id. | String |
| `when` | Required | Refers to the condition for executing the trigger on the custom entity.**Example:** `CREATE` | List |


[String] |
| `action`      | Required                 | Refers to the action performed when the trigger executes.For `SCRIPT`, this is Groovy script logic.For `RULE`, this is the rule id. | String   |
| `enabled`     | Optional                 | If `true`, the trigger is active.                                               | Boolean  |

#### Request

```bash
curl --location --request POST 'https://api3.sprinklr.com/{env}/api/v3/customEntity/trigger' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--data '{
  "entityType": "_c_caller_1",
  "type": "SCRIPT",
  "when": [
    "CREATE"
  ],
  "action": "after._c_notification_trigger_status = \"Triggered on create\" \nDB.save(after)",
  "enabled": true
}'
```

### 4.10 Update custom entity trigger

**`PUT /api/v3/customEntity/trigger?id={triggerId}`**

Triggers help perform intended actions on the custom entity based on the configured trigger conditions. Using this API, you can update the trigger configuration for a given trigger id.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | The trigger id received in the **Create Trigger API** response.**Example:** `6a986f685efb429a8039718f` | String |


#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `entityType` | Required | Refers to custom entity type, i.e., the custom entity definition Id.**Example:** `_c_caller_1` | String |
| `type` | Required | Refers to the type of trigger.Supported types:- `SCRIPT`: the action includes a script.- `RULE`: the action includes the rule id. | String |
| `when` | Required | Refers to the condition for executing the trigger on custom entity.**Example:** `CREATE` | List |


[String] |
| `action`      | Required                 | Refers to the action performed when the trigger executes.For `SCRIPT`, this is Groovy script logic.For `RULE`, this is the rule id. | String   |
| `enabled`     | Optional                 | If `true`, the trigger is active.                                               | Boolean  |

#### Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/customEntity/trigger?id=6a986f685efb429a8039718f' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--data '{
  "entityType": "_c_caller_1",
  "type": "SCRIPT",
  "when": [
    "CREATE"
  ],
  "action": "def consultant_ids = after._c_notification_consultant_id \n        if (consultant_ids == null || consultant_ids.size() == 0) { \n            after._c_notification_trigger_status = \"no users passed\" \n            DB.save(after) \n            return; \n        } \n        List> filters = COLLECTION_UTILS.newList(); \n        filters.add([federationId: consultant_ids]); \n        def users = DB.find(USER, [$and: filters], consultant_ids.size(), false, [[key: USER_ID, order: asc]]); \n        if (users == null || users.size() == 0) { \n            after._c_notification_trigger_status = \"no users found\" \n            DB.save(after) \n            return; \n        } \n        //collect user ids and add to custom entity \n        List userIds = COLLECTION_UTILS.newList(); \n        after._c_user_ids = COLLECTION_UTILS.newList(); \n        for (def user : users) { \n            userIds.add(user.id); \n            after._c_user_ids.add(String.valueOf(user.id)) \n        } \n            after._c_notification_trigger_status = \"SUCCESS\" \n        DB.save(after) \n        def notification = [body: after._c_notification_body, title: after._c_notification_title, action: after._c_notification_action, actionData: after._c_notification_action_data]; \n        PLATFORM.sendMobileNotification(notification, userIds, MAP_UTILS.newMap(), MAP_UTILS.newMap());",
  "enabled": true
}'
```

### 4.11 Patch custom entity trigger

**`PATCH /api/v3/customEntity/trigger?id={triggerId}`**

This API allows you to partially update an existing trigger configuration for a given trigger id. Unlike `PUT`, which replaces the entire configuration, `PATCH` modifies only the specified fields.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | The trigger id received in the **Create Trigger API** response.**Example:** `6a986f685efb429a8039718f` | String |


#### Request body parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `entityType` | Required | Refers to custom entity type, i.e., the custom entity definition Id.**Example:** `_c_caller` | String |
| `type` | Required | Refers to the type of trigger.Supported types:- `SCRIPT`: the action includes a script.- `RULE`: the action includes the rule id. | String |
| `when` | Required | Refers to the condition for executing the trigger on custom entity.**Example:** `UPDATE` | List |


[String] |
| `action`      | Required                 | Refers to the action performed when the trigger executes.For `SCRIPT`, this is Groovy script logic.For `RULE`, this is the rule id. | String   |
| `enabled`     | Optional                 | If `true`, the trigger is active.                                               | Boolean  |

#### Request

```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/customEntity/trigger?id=6a986f685efb429a8039718f' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--data '{
  "entityType": "_c_caller",
  "type": "SCRIPT",
  "when": [
    "UPDATE"
  ],
  "action": "def consultant_ids = after._c_notification_consultant_id \n        if (consultant_ids == null || consultant_ids.size() == 0) { \n            after._c_notification_trigger_status = \"no users passed\" \n            DB.save(after) \n            return; \n        } \n        List> filters = COLLECTION_UTILS.newList(); \n        filters.add([federationId: consultant_ids]); \n        def users = DB.find(USER, [$and: filters], consultant_ids.size(), false, [[key: USER_ID, order: asc]]); \n        if (users == null || users.size() == 0) { \n            after._c_notification_trigger_status = \"no users found\" \n            DB.save(after) \n            return; \n        } \n        //collect user ids and add to custom entity \n        List userIds = COLLECTION_UTILS.newList(); \n        after._c_user_ids = COLLECTION_UTILS.newList(); \n        for (def user : users) { \n            userIds.add(user.id); \n            after._c_user_ids.add(String.valueOf(user.id)) \n        } \n            after._c_notification_trigger_status = \"SUCCESS\" \n        DB.save(after) \n        def notification = [body: after._c_notification_body, title: after._c_notification_title, action: after._c_notification_action, actionData: after._c_notification_action_data]; \n        PLATFORM.sendMobileNotification(notification, userIds, MAP_UTILS.newMap(), MAP_UTILS.newMap());",
  "enabled": true
}'
```

## 5. Read operations

### 5.1 Read custom entity definition

**`GET /api/v3/customEntity/definition`**

Retrieves detailed information about a specific custom entity definition using its unique identifier. This endpoint is useful for inspecting the configuration of a custom entity, including its name, plural name, description, and metadata.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | Unique identifier of the custom entity definition.**Example:** `_c_spr_item_2` | String |


#### Request

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/customEntity/definition?id=_c_spr_item_2' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

### 5.2 Search custom entity definitions

**`GET /api/v3/customEntity/definition`**

Retrieves a paginated list of custom entity definitions. This endpoint is useful for browsing all available definitions in your environment, including their identifiers, names, plural names, and descriptions.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `pageNumber` | Optional | Page number to retrieve (0‑based index).**Example:** `0`, `1`, `2` | Number |


#### Request

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/customEntity/definition?pageNumber=0' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

### 5.3 Read custom entity field

**`GET /api/v3/customEntity/field`**

Retrieves detailed information about a specific custom entity field using its unique identifier. This endpoint is useful for inspecting the configuration of a field, including its API name, display name, type, and association with an entity definition.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | Unique identifier of the custom entity field.**Example:** `_c_spr_item_2__c_spr_item_2` | String |


#### Request

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/customEntity/field?id=_c_spr_item_2__c_spr_item_2' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

### 5.4 Read custom entity record

**`GET /api/v3/customEntity/entity`**

Retrieves detailed information about a specific custom entity record using its unique `entityId` and associated `entityDefinitionId`. This endpoint is useful for inspecting the values stored in a record.

#### Query parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `entityDefinitionId` | Required | The type of entity, that is, the unique identifier of the custom entity definition.**Example:** `_c_caller_1` | String |
| `entityId` | Required | The unique identifier for the created custom entity.This is the id you receive in the response of the **Create Custom Entity Record** API.**Example:** `6a984a0d5efb429a8039649b` | String |


#### Request

```bash
curl --location --request GET 'https://api3.sprinklr.com/{env}/api/v3/customEntity/entity?entityDefinitionId=_c_caller_1&entityId=6a984a0d5efb429a8039649b' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

## 6. Delete operations

### 6.1 Delete custom entity field

**`DELETE /api/v3/customEntity/field`**

Deletes an existing custom entity field. This endpoint permanently removes the field from the associated entity definition.
**Note:** Once deleted, the field cannot be used in records tied to the entity definition.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | Unique identifier of the custom entity field to delete.**Example:** `_c_spr_item_2__c_spr_item_2` | String |


#### Request

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/customEntity/field?id=_c_spr_item_2__c_spr_item_2' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

### 6.2 Delete custom entity record

**`DELETE /api/v3/customEntity/entity`**

Deletes an existing record for the custom entity definition. The `entityType` and `entityId` query parameters identify the record to delete. Once deleted, the record is permanently removed and cannot be recovered.

#### Query parameters

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `entityType` | Required | The type of entity, that is, the unique identifier of the custom entity definition.**Example:** `_c_caller_1` | String |
| `entityId` | Required | The unique identifier for the created custom entity.This is the id you receive in the response of the **Create Custom Entity Record** API.**Example:** `6a984a0d5efb429a8039649b` | String |


#### Request

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/customEntity/entity?entityType=_c_caller_1&entityId=6a984a0d5efb429a8039649b' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'
```

### 6.3 Delete custom entity trigger

**`DELETE /api/v3/customEntity/trigger?id={triggerId}`**

Deletes an existing trigger configuration for a given trigger id. Once deleted, the trigger will no longer execute for the associated custom entity.

#### Query parameter

| **Parameter** | **Required / Optional** | **Description** | **Type** |
|  --- | --- | --- | --- |
| `id` | Required | The unique reference id for the trigger you want to delete.You can fetch this id from the **Create Custom Entity Trigger API** response.**Example:** `6a986f685efb429a8039718f` | String |


#### Request

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/customEntity/trigger?id=6a986f685efb429a8039718f' \
--header 'Authorization: Bearer {Access Token}' \
--header 'Key: {API KEY}' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json'
```

## 7. Response format and status codes

### 7.1 The V3 envelope

Every Custom Entity V3 endpoint returns a consistent three‑part envelope:

```json
{
  "data": [ ... ],
  "errors": [],
  "metadata": {
    "totalCount": null,
    "hasMore": true,
    "pageNumber": 0,
    "pageSize": 10
  }
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `data` | Array[UnifiedProfile] | Array of profile objects matching the search criteria |
| `errors` | Array[Error] | Array of error objects (empty if no errors) |
| `metadata` | Object | Pagination and response metadata |
| `metadata.totalCount` | Integer/null | Total number of results (`null` for performance reasons) |
| `metadata.hasMore` | Boolean | Indicates if more pages are available |
| `metadata.pageNumber` | Integer | Current page number (0-based) |
| `metadata.pageSize` | Integer | Number of items per page |


### 7.2 Examples

#### Create Custom Entity Definition — Response

```json
{
    "data": {
        "id": "_c_caller_1",
        "name": "Caller ",
        "pluralName": "Callers",
        "description": "Describes Caller Data",
        "permissionEnabled": false,
        "createdTime": 1788353677812,
        "modifiedTime": 1788353677812
    },
    "errors": []
}
```

#### Update Custom Entity Definition — Response

```
204 No Content
```

#### Read Custom Entity Definition — Response

```json
{
    "data": [
        {
            "id": "_c_caller_1",
            "name": "Caller ",
            "pluralName": "Callers",
            "description": "Describes Caller Data",
            "permissionEnabled": false,
            "createdTime": 1788353677812,
            "modifiedTime": 1788353677812
        }
    ],
    "errors": []
}
```

#### Read All Custom Entities Definition — Response

```json
{
    "data": [
        {
            "id": "_c_testSourceRollUpEntityTen_1748584285",
            "name": "testSourceEntityTen_1748584285",
            "pluralName": "testSourceEntitiesTen_1748584285",
            "permissionEnabled": false,
            "createdTime": 1748584308388,
            "modifiedTime": 1748584308388
        },
        {
            "id": "_c_owned_post_creator_team",
            "name": "Owned Post Creator Team",
            "pluralName": "Owned Post Creator Teams",
            "permissionEnabled": false,
            "createdTime": 1693946952643,
            "modifiedTime": 1693946952643
        },
        {
            "id": "_s_Fin_Plan_c_FACT_67d23528834a865395db211f",
            "name": "FPRN-Leads-90f590a7-0a4a-440f-adfb-46e9510842d6",
            "baseDefinitionId": "_s_Fin_Plan",
            "permissionEnabled": true,
            "createdTime": 1741829416909,
            "modifiedTime": 1741829416909
        }
    ],
    "errors": [],
    "metadata": {
        "totalCount": 8499
    }
}
```

#### Create Custom Entity Field — Response

```json
{
    "data": {
        "id": "_c_caller__c_value_1",
        "apiName": "_c_value_1",
        "name": "Value",
        "type": "NUMBER",
        "entityDefinitionId": "_c_caller",
        "parentChild": false,
        "multivalued": false,
        "mandatory": false,
        "picklistValues": [
            {
                "label": "Kitty",
                "value": "cat",
                "active": true,
                "defaultValue": false
            },
            {
                "label": "Doggo",
                "value": "dog",
                "active": true,
                "defaultValue": true
            }
        ]
    },
    "errors": []
}
```

#### Update Custom Entity Field — Response

```json
{
    "data": {
        "id": "_c_caller__c_value_1",
        "apiName": "_c_value_1",
        "name": "Value",
        "type": "NUMBER",
        "entityDefinitionId": "_c_caller",
        "parentChild": false,
        "multivalued": false,
        "mandatory": false,
        "picklistValues": [
            {
                "label": "Kitty",
                "value": "cat",
                "active": true,
                "defaultValue": false
            },
            {
                "label": "Doggo",
                "value": "dog",
                "active": true,
                "defaultValue": true
            }
        ]
    },
    "errors": []
}
```

#### Read Custom Entity Field — Response

```json
{
    "data": [
        {
            "id": "_c_spr_item_2__c_spr_item_2",
            "apiName": "_c_spr_item_2",
            "name": "Product Catalog",
            "type": "TEXT",
            "entityDefinitionId": "_c_spr_item_2",
            "parentChild": false,
            "multivalued": false,
            "mandatory": false,
            "picklistValues": []
        }
    ],
    "errors": []
}
```

#### Delete Custom Entity Field — Response

```
204 No Content
```

#### Create Custom Entity Record — Response

```json
{
    "data": {
        "id": "6a984a0d5efb429a8039649b",
        "entityId": "6a984a0d5efb429a8039649b",
        "name": "Test",
        "type": "_c_caller_1",
        "values": {
            "_c_credit_score": 25,
            "_c_rating": 5,
            "_c_customer_bio": "Works in corporate"
        },
        "createdTime": "Wed Sep 02 16:08:46 UTC 2026",
        "createdTimeInMillis": 1788365326409,
        "modifiedTime": "Wed Sep 02 16:08:46 UTC 2026",
        "modifiedTimeInMillis": 1788365326409
    },
    "errors": []
}
```

#### Read Custom Entity Record — Response

```json

{
    "data": [
        {
            "id": "6a984a0d5efb429a8039649b",
            "entityId": "6a984a0d5efb429a8039649b",
            "name": "Test",
            "type": "_c_caller_1",
            "values": {
                "_c_credit_score": 25,
                "_c_rating": 5,
                "_c_customer_bio": "Works in corporate"
            },
            "createdTime": "Wed Sep 02 16:08:46 UTC 2026",
            "createdTimeInMillis": 1788365326409,
            "modifiedTime": "Wed Sep 02 16:08:46 UTC 2026",
            "modifiedTimeInMillis": 1788365326409
        }
    ],
    "errors": []
}
```

#### Update Custom Entity Record (PUT) — Response

```
204 No Content
```

#### Patch Custom Entity Record (PATCH) — Response

```
204 No Content
```

#### Delete Custom Entity Record — Response

```
204 No Content
```

#### Create Custom Entity Trigger — Response

```json
{
    "data": {
        "id": "6a99442b5efb429a8039cb70",
        "entityType": "_c_caller_1",
        "type": "SCRIPT",
        "when": [
            "CREATE"
        ],
        "action": "after._c_notification_trigger_status = \"Triggered on create\" \nDB.save(after)",
        "enabled": true,
        "createdTime": 1788429355789,
        "modifiedTime": 1788429355789
    },
    "errors": []
}
```

#### Update Custom Entity Trigger (PUT) — Response

```
204 No Content
```

#### Patch Custom Entity Trigger (PATCH) — Response

```
204 No Content
```

#### Read Custom Entity Trigger — Response

```json
{
    "data": [
        {
            "id": "6a99442b5efb429a8039cb70",
            "entityType": "_c_caller_1",
            "type": "SCRIPT",
            "when": [
                "CREATE"
            ],
            "action": "after._c_notification_trigger_status = \"Triggered on create\" \nDB.save(after)",
            "enabled": true,
            "createdTime": 1788429355789,
            "modifiedTime": 1788429355789
        }
    ],
    "errors": []
}
```

#### Delete Custom Entity Trigger — Response

```
204 No Content
```

### 7.3 Response codes

| HTTP Code | Scenario | Description |
|  --- | --- | --- |
| `200 OK` | Success | Profiles found and returned 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 `VIEW` permission for `AUDIENCE_PROFILE` |
| `404 Not Found` | No Profiles Found | No profiles match the search criteria |
| `500 Internal Server Error` | Server Error | Unexpected server-side error occurred |


## 8. V2 → V3 migration

The Custom Entity APIs have been redesigned in V3 for consistency and clarity.
Here’s a comparison of V2 vs V3 endpoints and behavior, grouped by operation type:

### Write operations (Create / Update / Patch)

| **Operation** | **V2 Endpoint** | **V3 Endpoint** | **Key Differences** |
|  --- | --- | --- | --- |
| Create Definition | `POST /api/v2/custom-entity/definition` | `POST /api/v3/customEntity/definition` | Path changed; V3 uses unified envelope. |
| Update Definition | `PUT /api/v2/custom-entity/definition/{id}` | `PUT /api/v3/customEntity/definition?id=` | V2 used path parameter; V3 uses query parameter. |
| Create Field | `POST /api/v2/custom-entity/field` | `POST /api/v3/customEntity/field` | Path changed; request/response envelope standardized. |
| Update Field | `PUT /api/v2/custom-entity/field/{id}` | `PUT /api/v3/customEntity/field?id=` | V2 used path parameter; V3 uses query parameter. |
| Create Record | `POST /api/v2/custom-entity/entity` | `POST /api/v3/customEntity/entity` | Path changed; V3 response envelope standardized. |
| Update Record (full) | `PUT /api/v2/custom-entity/entity/{entityId}` | `PUT /api/v3/customEntity/entity?entityType=&entityId=` | V2 used path parameter; V3 uses query parameter. |
| Update Record (partial) | `PATCH /api/v2/custom-entity/{definitionId}/{entityId}` | `PATCH /api/v3/customEntity/entity?entityType=&entityId=` | V2 used path parameters; V3 uses query parameters. |
| Upsert Record | `POST /api/v2/custom-entity/entity/upsert` | No V3 equivalent documented | Still only available in V2. |
| Bulk Create Records | `POST /api/v2/custom-entity/entity/bulk` | No V3 equivalent documented | Still only available in V2. |
| Create Trigger | `POST /api/v2/custom-entity/trigger` | `POST /api/v3/customEntity/trigger` | Path changed; V3 envelope standardized. |
| Update Trigger (full) | `PUT /api/v2/custom-entity/trigger/{id}` | `PUT /api/v3/customEntity/trigger?id=` | V2 used path parameter; V3 uses query parameter. |
| Update Trigger (partial) | `PATCH /api/v2/custom-entity/trigger/{id}` | `PATCH /api/v3/customEntity/trigger?id=` | V2 used path parameter; V3 uses query parameter. |
| Enable Trigger | `POST /api/v2/custom-entity/trigger/{id}/enable` | `PUT /api/v3/customEntity/trigger?id=&enabled=true` | V2 had a dedicated `/enable`; V3 folds enable/disable into update call. |


### Read operations (Fetch / Search)

| **Operation** | **V2 Endpoint** | **V3 Endpoint** | **Key Differences** |
|  --- | --- | --- | --- |
| Fetch Definition by ID | `GET /api/v2/custom-entity/definition/{id}` | `GET /api/v3/customEntity/definition?id=` | V2 used path parameter; V3 uses query parameter. |
| Fetch All Definitions | `GET /api/v2/custom-entity/definitions` | `GET /api/v3/customEntity/definition?pageNumber=` | V2 used plural path; V3 uses pagination metadata. |
| Fetch Fields by Definition | `GET /api/v2/custom-entity/fields/{definitionId}` | `GET /api/v3/customEntity/field?id=` | V2 used path parameter; V3 uses query parameter. |
| Fetch Record by ID | `GET /api/v2/custom-entity/entity/{definitionId}/{entityId}` | `GET /api/v3/customEntity/entity?entityType=&entityId=` | V2 used path parameters; V3 uses query parameters. |
| Search Records | `POST /api/v2/custom-entity/search/{definitionId}` | No V3 equivalent documented | Still only available in V2; continue using V2 for filtered search. |
| Fetch Trigger by ID | `GET /api/v2/custom-entity/trigger/{id}` | `GET /api/v3/customEntity/trigger?id=` | V2 used path parameter; V3 uses query parameter. |
| Fetch All Triggers | `GET /api/v2/custom-entity/triggers/{definitionId}/{type}` | `GET /api/v3/customEntity/trigger?pageNumber=` | V2 used path parameters; V3 uses pagination metadata. |


### Delete operations

| **Operation** | **V2 Endpoint** | **V3 Endpoint** | **Key Differences** |
|  --- | --- | --- | --- |
| Delete Field | `DELETE /api/v2/custom-entity/field/{id}` | `DELETE /api/v3/customEntity/field?id=` | V2 used path parameter; V3 uses query parameter. |
| Delete Record | `DELETE /api/v2/custom-entity/entity/{definitionId}/{entityId}` | `DELETE /api/v3/customEntity/entity?entityType=&entityId=` | V2 used path parameters; V3 uses query parameters. |
| Delete Trigger | `DELETE /api/v2/custom-entity/trigger/{id}` | `DELETE /api/v3/customEntity/trigger?id=` | V2 used path parameter; V3 uses query parameter. |