Custom Entity API V3 — Developer Guide

Applies to: Sprinklr Reporting Suite APIs V3
V2 API reference: Reporting Suite APIs | Sprinklr Developer Portal

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

3. Authentication and common headers

All Profile API calls are authenticated with OAuth 2.0. See 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

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

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

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

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

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

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

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

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

Request

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

Request

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

Request

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

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

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

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

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

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

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

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:

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

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

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

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

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

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

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

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


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

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

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