Standard entities are predefined data objects available in Sprinklr. Use Standard Entity API V3 to retrieve standard entity definitions and manage their fields and records programmatically. Standard entities are also available through Entity Studio, where you can view and manage structured business data in Sprinklr.
Standard Entity API provides operations for three resources:
| Resource | Description | Supported Operations |
|---|---|---|
| Definition | Describes a standard entity type | Read |
| Field | Defines a field associated with the entity | Create, read, update, delete |
| Record | Stores data associated with the entity | Create, read, update, patch, upsert, delete |
The V3 API reference exposes GET /standardEntity/definition, CRUD operations on /standardEntity/field, and CRUD plus upsert operations on /standardEntity/record.
Related Knowledge Base Article Entity Studio - An Overview
https://api3.sprinklr.com/{env}/api/v3/standardEntityReplace {env} with your assigned Sprinklr environment. See APIs | Sprinklr Developer Portal for the published environment list. For the production environment at app.sprinklr.com, omit the {env} segment from the URL.
The resources covered in this guide are:
/standardEntity/definition
/standardEntity/field
/standardEntity/record
/standardEntity/record/upsertStandard Entity API V3 requires bearer-token and API-key authentication. The definition, field, and record API references specify both bearerAuth and apiKeyAuth.
| Header | Value | Required |
|---|---|---|
Authorization | Bearer {{accessToken}} | Yes |
Key | {{apiKey}} | Yes |
Content-Type | application/json | Requests with a body |
Accept | application/json | Recommended |
An entity definition describes the standard entity, including its name, description, base definition, permission settings, and other metadata. Standard Entity API V3 provides a read operation for retrieving a definition by entityType.
Retrieve the definition of a standard platform entity by entity type.
GET /api/v3/standardEntity/definitionQuery Parameter | Parameter | Type | Required | Description | |---|---|---|---|---| | entityType | string | Yes | Type of standard entity to retrieve, for example _s_Consent. Supported entity Ids: _s_Consent, _s_PublishingQueue, _s_ConsentCatalogue, _s_PriceBook, _s_PublisherSettings |
Example Request
curl -X GET \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/definition?entityType=_s_Consent' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Accept: application/json'The response can include fields such as id, name, pluralName, description, baseDefinitionId, icon, permissionEnabled, createdTime, and modifiedTime.
Fields define the information stored for a standard entity. Standard Entity API V3 supports retrieving, creating, updating, and deleting fields.
Fetch fields by ID or by field name, with pagination.
GET /api/v3/standardEntity/field| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fieldId | query | string | Conditional | Comma-separated list of field IDs |
fieldName | query | string | Conditional | Field name |
entityDefinitionId | query | string | Conditional | The definition the field belongs to. Required when identifying a field by fieldName |
pageNumber | query | integer | No | Page number, 0-based |
pageSize | query | integer | No | Number of results per page. Maximum 100 |
The API supports fetching fields by ID or field name and listing fields with pagination.
Example: Fetch a field by name
curl -X GET \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?fieldName=_c_ConsentName&entityDefinitionId=_s_Consent' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Accept: application/json'Example: List fields
curl -X GET \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?entityDefinitionId=_s_Consent&pageNumber=0&pageSize=100' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Accept: application/json'POST /api/v3/standardEntity/fieldSend the field definition in the request body. The field schema supports properties such as apiName, name, description, type, entityDefinitionId, multivalued, mandatory, picklist configuration, and type-specific information.
Send the field definition in the request body. There are no query parameters.
| Body field | Type | Required | Description |
|---|---|---|---|
apiName | string | Yes | The API name for the field. Prefix custom fields with _c_ |
name | string | No | A human-readable name describing the field's purpose |
type | string | Yes | The field's data type. Supported values include TEXT, DATE, BOOLEAN, NUMBER, DOUBLE, INTEGER |
entityDefinitionId | string | Yes | The definition to add the field to |
Example Request
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
"apiName": "_c_ConsentName",
"name": "User Consent Name",
"type": "TEXT",
"entityDefinitionId": "_s_Consent"
}'PUT /api/v3/standardEntity/fieldIdentify the field and send the updated field definition in the request body. The field resource exposes PUT as its update operation.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
fieldId | query | string | Conditional | The field ID |
fieldName | query | string | Conditional | The field name |
entityDefinitionId | query | string | Conditional | Required when using fieldName |
Send the updated field object in the request body. Identify the field by either fieldId or fieldName, not both.
Example Request
curl -X PUT \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?fieldName=_c_ConsentName&entityDefinitionId=_s_Consent' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
"apiName": "_c_ConsentName",
"name": "Consent Full Name",
"type": "TEXT",
"entityDefinitionId": "_s_Consent"
}'You can identify fields by ID or field name. When using fieldName, provide entityDefinitionId. The delete operation supports a comma-separated list of field IDs.
DELETE /api/v3/standardEntity/field| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | query | string | Conditional | Comma-separated list of field IDs |
fieldName | query | string | Conditional | The field name |
entityDefinitionId | query | string | Conditional | Required when using fieldName |
Example Request
curl -X DELETE \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?id=0000000000000000000000a1,0000000000000000000000a2&entityDefinitionId=_s_Consent' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}'Deleting a field removes it from the definition. Data stored in that field on existing records is no longer retrievable through the API. Confirm before you delete.
Records contain the data stored for a standard entity. Standard Entity API V3 supports fetching, creating, replacing, partially updating, upserting, and deleting records.
Fetch records by entity ID, record ID, primary key, or primary key prefix.
GET /api/v3/standardEntity/record| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
entityType | query | string | Yes | The definition to search in, for example _s_Consent |
entityId | query | string | Conditional | Comma-separated list of entity IDs |
recordId | query | string | Conditional | Comma-separated list of record IDs |
primaryKey | query | string | Conditional | Primary key exact lookup |
primaryKeyPrefix | query | string | Conditional | Primary key prefix lookup |
pageNumber | query | integer | No | Page number, 0-based |
pageSize | query | integer | No | Number of results per page. Maximum 100 |
The current API supports lookup using entity ID, record ID, primary key, or primary-key prefix. entityType identifies the type of standard entity being queried.
Example Request
curl -X GET \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=6321e6684eed2b006dc0abdb' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Accept: application/json'The response is an array of record objects and can include fields such as id, entityId, name, type, values, processedValues, tags, archived, entityMetadata, and createdBy.
POST /api/v3/standardEntity/recordSend the record in the request body. The values you provide depend on the fields configured for the entity definition.
Example Request
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
"type": "_s_Consent",
"entityId": "consent-jane-doe-001",
"identityType": "PHONE",
"identityId": "15550100",
"channel": "FACEBOOK"
}'Before creating records, retrieve the entity's fields to understand the schema expected by that entity.
Use PUT to update a record:
PUT /api/v3/standardEntity/recordIdentify the record using the applicable record identifier and provide the updated record in the request body. PUT is one of the supported operations on the V3 standard-entity record resource.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
entityType | query | string | Yes | The definition |
entityId | query | string | Conditional | The entity ID |
recordId | query | string | Conditional | The record ID |
PUT replaces the record with the body you send. Include the primary fields, and make sure they match the values used at create time.
curl -X PUT \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=consent-jane-doe-001' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
"type": "_s_Consent",
"entityId": "consent-jane-doe-001",
"identityType": "PHONE",
"identityId": "15550100",
"channel": "FACEBOOK"
}'Use PATCH when you need to update specific portions of an existing record rather than replacing it. PATCH /standardEntity/record is included in the currently published V3 operations.
PATCH /api/v3/standardEntity/record| Body field | Type | Required | Description |
|---|---|---|---|
updateFields | array | Yes | List of updates to apply |
updateFields[].fieldName | string | Yes | The field to change |
updateFields[].value | any | Yes | The new value |
updateFields[].op | string | Yes | The operation to apply. One of FIND, INSERT, PATCH, UPDATE, DELETE |
Example Request
curl -X PATCH \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=consent-jane-doe-001' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
"updateFields": [
{ "fieldName": "_c_ConsentName", "value": "Jane Doe", "op": "UPDATE" }
]
}'Use the upsert operation to create or update a standard entity record:
POST /api/v3/standardEntity/record/upsertCreates the record if it does not exist, updates it if it does. Send the record in the request body; there are no query parameters. The current V3 API exposes /standardEntity/record/upsert as a separate POST operation with the standard entity record object in the request body.
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record/upsert' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
"type": "_s_Consent",
"entityId": "consent-jane-doe-001",
"identityType": "PHONE",
"identityId": "15550100",
"channel": "FACEBOOK"
}'DELETE /api/v3/standardEntity/recordThe record resource supports deletion in addition to its create, retrieve, update, partial-update, and upsert operations.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
entityType | query | string | Yes | The definition |
entityId | query | string | Conditional | Comma-separated list of entity IDs |
recordId | query | string | Conditional | Comma-separated list of record IDs |
curl -X DELETE \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/record?entityType=_s_Consent&entityId=consent-jane-doe-001,consent-jane-doe-002' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}'All responses use the standard envelope:
{
"data": {},
"errors": [],
"metadata": {}
}Each entry in errors has this shape:
| Field | Type | Description |
|---|---|---|
id | string | 24-character hex ObjectId for the error occurrence |
code | integer | The status code |
message | string | A dotted error key or a descriptive message |
The definition, field, and record API references currently advertise the same set of HTTP responses.
| Code | Meaning | Common causes |
|---|---|---|
200 | OK | The request succeeded |
400 | Bad request | The request is invalid |
401 | Unauthorized | Authentication failed. Missing, expired, or mismatched credentials; wrong {env} in the URL |
403 | Forbidden | The authenticated user is not authorized to perform the operation |
404 | Not found | The requested resource was not found |
API V3 uses the standardEntity resource namespace:
/api/v3/standardEntityFor V2 - /api/v2/standard-entity/...
For V3 - /api/v3/standardEntity/...The V3 API consolidates standard entity operations under definition, field, and record resources. When migrating, update the endpoint paths and validate request parameters and response structures against the V3 API reference rather than assuming that the V2 and V3 contracts are identical. The current V3 resources expose one definition operation, four field operations, and record operations for retrieve, create, update, patch, delete, and upsert.
curl -X GET \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field?entityDefinitionId=_s_Consent&pageNumber=0&pageSize=100' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}'Look at mandatory and type on every field returned. Those two properties tell you exactly what a valid record payload must contain.
curl -X POST \
'https://api3.sprinklr.com/{env}/api/v3/standardEntity/field' \
-H 'Authorization: Bearer {{accessToken}}' \
-H 'Key: {{apiKey}}' \
-H 'Content-Type: application/json' \
-d '{
"apiName": "_c_LoyaltyTier",
"name": "Loyalty Tier",
"type": "TEXT",
"entityDefinitionId": "_s_Consent"
}'Use POST /standardEntity/record/upsert with an entityId derived from your own system's primary key. Every sync run then becomes idempotent — no existence check, no branch between create and update.
Use PATCH with a single entry in updateFields. This is safer than PUT, which replaces the whole record.
Start at pageNumber=0, request pageSize=100, and stop when a page returns fewer than 100 results.
- Set your own
entityIdat create time. Derive it from your source system's key. Every later lookup, update, upsert, and delete becomes trivial, and your integration stops needing a local id mapping table. - Read the field list before you write records. The
mandatoryflag is the authoritative list of what a payload must contain — do not hard-code it. - Prefer
PATCHtoPUT. It avoids clearing fields you forgot to include and avoids the primary-field matching trap. - Prefer
upsertfor synchronisation jobs. It removes an entire round trip and a race condition. - Never change a primary field on an update. It will not update the record.
- Give every integration its own API key. Sharing a key across services means refreshing one token silently breaks the others.
- Cache the definition and field list. They change rarely. Re-reading them on every record write is wasted latency.
- Store the field
idreturned at create time. Referencing a field byidavoids having to sendentityDefinitionIdalongsidefieldNameon every call. - Check
dataanderrorson every multi-id call. Partial success is a normal outcome, not an edge case. - Batch conservatively. Comma-separated id lists are supported, but keep them to a reasonable size so that a partial failure is easy to interpret and retry.
| Message or symptom | Cause | Fix |
|---|---|---|
Valid query params must be provided for standardEntityField retrieval. Provide one from: 'fieldName' or 'id' along with any additional required param as per documentation. | No field identifier was sent | Send either fieldName (with entityDefinitionId) or the field id |
Only one of 'fieldName' or 'id' can be provided for StandardEntityField retrieval. Provided: 'fieldName' and 'id'. Choose the appropriate identifier. | Both identifiers were sent | Send exactly one |
Valid query params must be provided for standardEntity retrieval. Provide one from: 'recordId' or 'entityId' or 'primaryKey' along with any additional required param as per documentation. | No record identifier was sent | Send one of recordId, entityId, or primaryKey, together with entityType |
Invalid 'pageSize' parameter. Must be a positive integer not exceeding 100. | Page size above 100, or zero or negative | Use a value from 1 to 100 |
Invalid 'pageNumber' parameter. Must be a non-negative integer (page number begins with 0). | Page number is negative, or your client starts paging at 1 | Start at 0 |
Entity type _s_SurveyResponseTranslation does not have primary key columns defined | Primary key lookup attempted on a type with no primary keys | Look the record up by entityId or recordId instead |
StandardEntityField not found for fieldName: '...'. Verify the standardEntityField exists and you have access permissions. | The field does not exist on that definition, or you cannot see it | Check the apiName spelling and the entityDefinitionId; confirm the key owner's permissions |
StandardEntity not found for entityId: '...'. Verify the standardEntity exists and you have access permissions. | The record does not exist, or you cannot see it | Confirm the entityId and entityType; confirm permissions |
401 Unauthorized on every call | Missing Key header, expired token, or wrong {env} | Send both Authorization and Key; confirm the environment; regenerate the token if older than 30 days |
401 appearing intermittently across services | Two services share one API key, and each token refresh invalidates the other | Issue a separate API key per integration |
| An update returns success but the record is unchanged | A primary field value differs from the one used at create time, so no record matched | Keep identityType, identityId, and channel identical to the create call |
A PUT cleared fields you did not intend to change | PUT replaces the whole record | Use PATCH with updateFields |
| A multi-record delete "succeeded" but records remain | Delete reports per-record outcomes | Read the errors array as well as data |