Custom Field API V3 — Developer Guide

• V2 API reference: Custom Field | Sprinklr Developer Portal

A Custom Field is a fully customizable property or tag that can be created at several feature levels (for various assets) to organize and categorize content. Custom fields are managed in the Sprinklr UI under All Settings → Manage Workspace → Custom Fields, and through this API.

Custom Field V3 exposes create, read, and update on a single resource path — /api/v3/customField — differentiated by HTTP method:

This is the central design change from V2, which spread the same capabilities across four separate kebab-case paths (/api/v2/custom-field, /api/v2/custom-field/{customFieldName}, and the option-update endpoint). The V3 change set is:

• Kebab-case paths converted to camelCase (custom-field → customField).
• Path-based parameters replaced by query parameters, per V3 convention.
• No changes to request body fields for POST and PUT requests.

For endpoint-level reference documentation, see the Custom Field V3 tag in the V3 OpenAPI specification (operationId values CustomFieldApiV3_getCustomField, CustomFieldApiV3_createCustomField, CustomFieldApiV3_updateCustomField, CustomFieldApiV3_patchCustomFieldOptions).

A custom field is addressed in two ways, and the two are mutually exclusive:

• By field name — fieldName, the API name, for example _c_62fc7b88b893784e3db68fa1
• By Sprinklr ID — id, for example 69f021fb6357c2c9885e0eb5

Both fieldName and id on GET, PUT, and PATCH, are "mutually exclusive with" the other. The acceptance criteria is GET by ?fieldName= and PUT/PATCH by ?id=; both parameters are accepted on all three methods per the specification.

To find fieldName in the UI: hamburger menu → All Settings → Custom Fields (under Manage Workspace) → three dots next to the field → Copy Field Name.

All API calls are sent to the production endpoint:

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

So the custom field resource in production is:

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

Replace {env} with your assigned environment identifier (prod0, prod2, prod11, and so on — see APIs | Sprinklr Developer Portal for the environment list).

All Custom Field API calls are authenticated with OAuth 2.0. See API Overview for portal registration, API key and secret generation, and the Authorize flow.

POST /api/v3/customField

Creates a new custom field. The request body is the CustomField schema and is unchanged from API v2.

Dev note: when applying controlling custom field logic, the asset type for both the controlling and the controlled custom field must be the same.

curl --location 'https://api3.sprinklr.com/{env}/api/v3/customField' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "type": "PICKLIST",
  "label": "Buy text books",
  "description": "Text books",
  "assetTypes": [
    "UNIVERSAL_CASE"
  ],
  "valuesOptions": [
    { "label": "Hindi Book",   "value": "Item3" },
    { "label": "English Book", "value": "Item4" },
    { "label": "Maths Book",   "value": "Item5" }
  ],
  "enabled": true,
  "visibility": {
    "globallyVisible": true,
    "visibilityConfig": []
  },
  "permissions": [],
  "optionType": "GENERAL"
}'

The response remains wrapped in the { "data": { … }, "errors": [] } envelope, as in V2.

{
  "data": {
    "id": "6a15774f00f392c2e656e68b",
    "fieldName": "_c_6a15774e00f392c2e656e688",
    "label": "Buy text books",
    "description": "Text books",
    "assetTypes": [
      "CASE"
    ],
    "type": "PICKLIST",
    "valuesOptions": [
      { "label": "Hindi Book",   "value": "Item3" },
      { "label": "English Book", "value": "Item4" },
      { "label": "Maths Book",   "value": "Item5" }
    ],
    "enabled": true,
    "visibility": {
      "globallyVisible": true,
      "visibilityConfig": []
    },
    "permissions": [],
    "optionType": "GENERAL",
    "createdTime": 1779791695119,
    "modifiedTime": 1779791695119
  },
  "errors": []
}

Both keys represent picklist options, and they have different shapes:

Note the inversion: values[].key carries the stored value, while valuesOptions[].value carries it. Do not map key → label positionally between the two.

PUT /api/v3/customField?id={customFieldId}

The fields present in the body are merged into the existing custom field. PUT retains full update semantics and that the request body fields are unchanged from V2.

Supply exactly one of the two.

Only these fields are merged into the existing field when present:

type, label, and fieldName are not in the update schema. See the type-change caveat below.

curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/customField?id=69f021fb6357c2c9885e0eb5' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "description": "Updated description",
  "category": "Support",
  "enabled": true,
  "assetTypes": [
    "UNIVERSAL_CASE"
  ],
  "valuesOptions": [
    { "label": "Yes",   "value": "Yes" },
    { "label": "No",    "value": "No" },
    { "label": "Maybe", "value": "Maybe" }
  ],
  "langVsTranslatedFieldValues": {
    "es_ES": { "description": "Descripción actualizada" }
  }
}'

PUT responds 204 No Content with no response body.

Updating the field type — for example PICKLIST → PICKLIST_MULTISELECT — is not supported. "the v2 api did not have support for updating the type. The same behaviour exists here as well."

What this means for you: do not send type in an update payload and do not rely on the response status to tell you a type change was rejected. If you need a different type, create a new custom field.

PATCH /api/v3/customField?id={customFieldId}

Adds new picklist options and deletes existing ones without resending the full option set, and optionally applies the same merge fields as PUT. The OpenAPI summary is "Partial update (picklist options and/or PUT-merge fields)".

Identical to PUT: id or fieldName, mutually exclusive.

CustomFieldOption_metadata item fields: label, value, category, additional (Map[String,String]), langVsTranslatedFieldValues.

curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/customField?id=69f179317de8c9de2ad70475' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "addedValuesOptions": [
    { "label": "Optical1", "value": "test1" },
    { "label": "Optical2", "value": "test2" }
  ],
  "removedValuesOptions": [
    "Item5"
  ]
}'

PATCH responds 204 No Content with no response body.

Only PICKLIST and PICKLIST_MULTISELECT field types support option updates via PATCH.

PUT and PATCH take different body schemas. You cannot reuse one payload for both methods.

Choosing the right option operation:

Using valuesOptions where you meant addedValuesOptions replaces the whole option set and drops every option you did not resend.

Fetches custom field details by field name or by ID. Replaces the V2 path-parameter endpoint.

# By field name — the primary lookup per IN-12885
curl --location 'https://api3.sprinklr.com/{env}/api/v3/customField?fieldName=_c_62fc7b88b893784e3db68fa1' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

# By ID
curl --location 'https://api3.sprinklr.com/{env}/api/v3/customField?id=6a15774f00f392c2e656e68b' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

The OpenAPI document types the GET 200 response as an array of CustomField, whereas POST returns a single CustomField. Handle the read response as a collection even when you addressed a single field.

{
  "data": [
    {
      "id": "62fc7b88b893784e3db68fa6",
      "fieldName": "_c_62fc7b88b893784e3db68fa1",
      "label": "profile check",
      "assetTypes": [
        "PROFILE"
      ],
      "type": "PICKLIST_MULTISELECT",
      "values": [
        { "key": "Tag",  "label": "Tag" },
        { "key": "Tag1", "label": "Tag1" }
      ],
      "category": "",
      "enabled": true,
      "visibility": {
        "globallyVisible": true,
        "visibilityConfig": []
      },
      "permissions": []
    }
  ],
  "errors": []
}

POST responses use the two-part envelope:

{
  "data": { },
  "errors": []
}

PUT and PATCH return no body.

The single biggest structural change: V2 used path parameters on kebab-case paths (/custom-field/{customFieldName}); V3 uses query parameters on one camelCase path (/customField?fieldName=).

Only PICKLIST and PICKLIST_MULTISELECT accept option definitions and option updates.

ACCOUNT, OUTBOUND_MESSAGE, MESSAGE, PROFILE, MEDIA_ASSET, USER, CAMPAIGN, SUB_CAMPAIGN, COMMUNITY, PRODUCT, PAID_INITIATIVE, AD_SET, AD_VARIANT, CASE, UNIVERSAL_CASE, SURVEY, TASK.

Issue a single POST /api/v3/customField with type: "PICKLIST", the target assetTypes, and the full valuesOptions set. Capture data.fieldName (_c_…) from the response and store it — it is the addressing key for every later read and update, and it is also the key you use when writing values onto a profile or case.

Do not GET, mutate, and PUT the whole option list — a concurrent editor's option would be lost. Use:

{ "addedValuesOptions": [ { "label": "Priority Support", "value": "priority_support" } ] }

PATCH takes a distributed lock on the field (added under IN-13211), so concurrent adds do not clobber each other.

{ "removedValuesOptions": ["legacy_plan"] }

Removing an option does not delete the field. If you need the whole field out of circulation, PATCH with {"enabled": false} instead — there is no delete endpoint.

Translations live in langVsTranslatedFieldValues, at both field level and option level:

{
  "valuesOptions": [
    {
      "label": "Hindi Book",
      "value": "Item3",
      "langVsTranslatedFieldValues": {
        "es_ES": { "label": "Libro de hindi" }
      }
    }
  ],
  "langVsTranslatedFieldValues": {
    "es_ES": { "description": "Descripción actualizada" }
  }
}

This is exactly why valuesOptions exists alongside values: KeyLabelPair has no translation slot.

Set customFieldControllerById, keyed by the controlling field's id, on the controlled field:

{
  "customFieldControllerById": {
    "66b0b924b8f96b59e3003ce3": {
      "controllingFieldConfig": {
        "option 1": ["test1"],
        "option 2": ["test2"]
      }
    }
  }
}

When option 1 is selected on the controlling field, only test1 is offered on this field. Both fields must share the same asset type.

GET /api/v3/customField?fieldName=_c_62fc7b88b893784e3db68fa1 returns the definition, including type — check it before sending option edits, since only PICKLIST and PICKLIST_MULTISELECT accept them.

When your system owns the complete option set (for example, a product catalog), compute the delta and send one PATCH:

{
  "addedValuesOptions": [
    { "label": "Model X2", "value": "model_x2" }
  ],
  "removedValuesOptions": ["model_w1"]
}

A delta PATCH is safer than a wholesale valuesOptions replacement because it leaves options added by other systems intact.

Method selection

• PUT and PATCH take different body schemas. Payloads are not interchangeable.
• Use PATCH for incremental option work; reserve full valuesOptions replacement for when you own the entire list.
• There is no delete. Plan for enabled: false as the retirement mechanism.

Identifiers

• fieldName and id are mutually exclusive on GET, PUT, and PATCH. Send exactly one.
• fieldName values are prefixed _c_. Copy them from the create response or from the UI (Copy Field Name).
• Send option value / key as strings, not numbers (IN-13205).

Types

• type cannot be changed after creation. Create a new field instead.
• Option fields are meaningful only for PICKLIST and PICKLIST_MULTISELECT.

Response handling

• Treat 200 (read/create) and 204 (update) both as success; do not assert on a single status code.
• Do not attempt to parse an update response body — there is none.
• Accept both values and valuesOptions when reading options, and mind the key ↔ value inversion.
• Do not assume assetTypes round-trips exactly as sent.

Governance

• If visibilityConfig is populated, globallyVisible must be false.
• permissions[].spaceType and permissions[].spaceId are both required whenever a Permission entry is supplied.

Constraints carried from V2

• description should not exceed 500 characters.
• A controlling field and its controlled field must share the same asset type.

All JSON payloads in this guide are illustrative examples. They are not real customer data and are not guaranteed production responses. All credentials are placeholders ({{accessToken}}, {{apiKey}}) and must never be committed or logged.