# Standard Entity API 3.0

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://www.sprinklr.com/help/articles/entity-studio-an-overview/entity-studio-an-overview/693a9c231db8130c76d78b40)


## Base URL

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

Replace `{env}` with your assigned Sprinklr environment. See [APIs | Sprinklr Developer Portal](https://dev.sprinklr.com/apis) 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/upsert
```

## Authentication

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


## Entity Definitions

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.

### Fetch a definition

Retrieve the definition of a standard platform entity by entity type.

```
GET /api/v3/standardEntity/definition
```

**Query 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**

```bash
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.

## Standard Entity Fields Operations

Fields define the information stored for a standard entity. Standard Entity API V3 supports retrieving, creating, updating, and deleting fields.

### Fetch fields

Fetch fields by ID or by field name, with pagination.

```
GET /api/v3/standardEntity/field
```

#### Query Parameters

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

```bash
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**

```bash
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'
```

### Create a field

```
POST /api/v3/standardEntity/field
```

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

#### Request Parameters

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

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

### Update a field

```
PUT /api/v3/standardEntity/field
```

Identify 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**

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

### Delete fields

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

```bash
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.

## Standard Entity Records

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

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

```bash
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.

### Create a record

```
POST /api/v3/standardEntity/record
```

Send the record in the request body. The values you provide depend on the fields configured for the entity definition.

**Example Request**

```bash
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.

### Replace a record

Use PUT to update a record:

```
PUT /api/v3/standardEntity/record
```

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

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

### Partially update a record

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

```bash
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" }
    ]
  }'
```

### Upsert a record

Use the upsert operation to create or update a standard entity record:

```
POST /api/v3/standardEntity/record/upsert
```

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

```bash
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 records

```
DELETE /api/v3/standardEntity/record
```

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


```bash
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}}'
```

## Response format and status codes

All responses use the standard envelope:

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


### Status codes

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 |


## Migrate from API 2.0

API V3 uses the standardEntity resource namespace:

```
/api/v3/standardEntity
```

```
For 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.

## Common Use Cases

### Discover the schema before you write anything

```bash
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.

### Add a custom field to an existing definition

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

### Keep an external system in sync

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.

### Update one field without touching the rest

Use `PATCH` with a single entry in `updateFields`. This is safer than `PUT`, which replaces the whole record.

### Page through a large result set

Start at `pageNumber=0`, request `pageSize=100`, and stop when a page returns fewer than 100 results.

## Best practices

- **Set your own `entityId` at 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 `mandatory` flag is the authoritative list of what a payload must contain — do not hard-code it.
- **Prefer `PATCH` to `PUT`.** It avoids clearing fields you forgot to include and avoids the primary-field matching trap.
- **Prefer `upsert` for 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 `id` returned at create time.** Referencing a field by `id` avoids having to send `entityDefinitionId` alongside `fieldName` on every call.
- **Check `data` and `errors` on 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.


## Troubleshooting

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