Developer Documentation

Create Data Field

post https://{host}/api_gateway/cortex/v1/dataFields

This API allows you to define specific data fields that you want to include in the entity search at organisation level.

👍

Note:

For detailed information about the APIs and for hands-on testing, refer to the API overview documentation and the step-by-step guide on making your first API call.

This API lets you specify which data fields should be included when performing an entity search at the organisation level. The fields you define here will automatically be included in the Cortex Search API (/api_gateway/cortex/v1/criteria) response for that specific organisation.

API Endpoint

{host}/api_gateway/cortex/v1/dataFields

Request Body Parameters

ParameterData TypeDescription
searchStrategyType*StringDefines the search strategy type (COMBINATION, PREFIX)
entityType*EnumType of entity being searched (TRANSACTION, CUSTOMER)
dataFieldDefinitions*ArrayList of field definitions used in the search.
- fieldId*StringThe field to search on. For Customer, the supported standard fields are: firstName, lastName, email, mobile, externalId, and fullName.
For Transaction, the supported fields are: outlierStatus, billDate, billNumber, and storecode (additional field).
- fieldAliasStringThe alias or display name of the field
- fieldTypeEnumType of field. Use the field type 'DATA'
- dataSourceDetailsObjectContains details about the data source.
-- fieldReferenceStringApplicable when using custom fields or extended fields. Ex: extendedFields.ship_email, customFields.age. If you are using store code to search, use additionalFields.storecode (applicable for transaction).
- dataTypeStringData type of the field (STRING, NUMBER, DECIMAL, or DATE).
curl --location 'eu.api.capillarytech.com/api_gateway/cortex/v1/dataFields' \
--header 'Authorization: Basic bmVlcmFqLmRvNGFmDA0MDA5Y2IwMzZhNGNjZGMzMzQzMWVmOWFjOQ==' \
--header 'Content-Type: application/json' \
--header 'Cookie: _cfuvid=NIG4hPIouTlCOXgwODX50uFuouza2nwDNThbawZibQM-1743137683215-0.0.1.1-604800000' \
--data '{
  "searchStrategyType" : "PREFIX",
  "entityType" : "CUSTOMER",
  "dataFieldDefinitions" : [
		{
			"fieldId" : "firstName",
			"fieldAlias" : "firstName",
			"fieldType" : "DATA",
			"dataSourceDetails" : {
				"fieldReference" : "firstName"
			},
			"dataType" : "STRING"
		},
		{
			"fieldId" : "lastName",
			"fieldAlias" : "lastName",
			"fieldType" : "DATA",
			"dataSourceDetails" : {
				"fieldReference" : "lastName"
			},
			"dataType" : "STRING"
		},
		{
			"fieldId" : "mobile",
			"fieldAlias" : "mobile",
			"fieldType" : "DATA",
			"dataSourceDetails" : {
				"fieldReference" : "mobile"
			},
			"dataType" : "STRING"
		},
		{
			"fieldId" : "email",
			"fieldAlias" : "email",
			"fieldType" : "DATA",
			"dataSourceDetails" : {
				"fieldReference" : "email"
			},
			"dataType" : "STRING"
		},
    {
			"fieldId" : "externalId",
			"fieldAlias" : "externalId",
			"fieldType" : "DATA",
			"dataSourceDetails" : {
				"fieldReference" : "externalId"
			},
			"dataType" : "STRING"
		}

	]
}'

curl --location 'eu.api.capillarytech.com/api_gateway/cortex/v1/dataFields' \
--header 'Authorization: Basic bmVlcmFqLmRvYzpiNGFmODDA5Y2IwMzZhNGNjZGMzMzQzMWVmOWFjOQ==' \
--header 'Content-Type: application/json' \
--header 'Cookie: _cfuvid=NIG4hPIouTlCOXgwODX50uFuouza2nwDNThbawZibQM-1743137683215-0.0.1.1-604800000' \
--data '{
"searchStrategyType" : "COMBINATION",
	"entityType" : "TRANSACTION",
  "dataFieldDefinitions" :
   [
		{
			"fieldId" : "billNumber",
			"fieldAlias" : "billNumber",
			"fieldType" : "DATA",
			"dataSourceDetails" : 
            {
				"fieldReference" : "billNumber"
			},
			"dataType" : "STRING"
		},
    {
			"fieldId" : "billDate",
			"fieldAlias" : "billDate",
			"fieldType" : "DATA",
			"dataSourceDetails" : {
				"fieldReference" : "billDate"
			},
			"dataType" : "DATE"
		},
    {
      "fieldId" : "storename",
      "fieldAlias" : "storename",
      "fieldType" : "DATA",
      "dataSourceDetails" : {
        "fieldReference" : "additionalFields.storename"
      },
      "dataType" : "STRING"
    },
    {
      "fieldId" : "storecode",
      "fieldAlias" : "storecode",
      "fieldType" : "DATA",
      "dataSourceDetails" : {
        "fieldReference" : "additionalFields.storecode"
      },
      "dataType" : "STRING"
    }
    
	]

}'

Response Parameters

ParametersData typeDescription
idStringUnique Identifier of the data
orgIdIntegerThe ID of the organization associated with the criteria
searchStrategyTypeEnumDefines the search strategy type (`COMBINATION, PREFIX )
entityTypeEnumType of entity being searched (TRANSACTION , CUSTOMER)
dataFieldDefinitionsArrayList of field definitions used in the search.
- fieldIdStringUnique identifier for the field.
- fieldAliasStringThe alias or display name of the search field.
- fieldTypeEnumType of field (e.g., INDEXED, FILTERABLE).
- dataSourceDetailsObjectContains details about the data source.
-- fieldReferenceStringThe reference to the search field in the data source.
- dataTypeStringData type of the field (e.g., STRING, DATE).
auditInfoObjectAn object containing audit information about the criteria.
- createdOnStringThe timestamp indicating when the criteria was created.
- createdByIntegerThe ID of the user who created the criteria.
- lastUpdatedOnStringThe timestamp indicating when the search criteria was last updated.
- lastUpdatedByIntegerThe ID of the user who last updated the criteria.
{
    "data": {
        "id": "67e6a8bfdd6a186b5555ba98",
        "orgId": 100737,
        "searchStrategyType": "PREFIX",
        "entityType": "CUSTOMER",
        "dataFieldDefinitions": [
            {
                "fieldId": "firstName",
                "fieldAlias": "firstName",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "firstName"
                },
                "dataType": "STRING"
            },
            {
                "fieldId": "lastName",
                "fieldAlias": "lastName",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "lastName"
                },
                "dataType": "STRING"
            },
            {
                "fieldId": "mobile",
                "fieldAlias": "mobile",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "mobile"
                },
                "dataType": "STRING"
            },
            {
                "fieldId": "email",
                "fieldAlias": "email",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "email"
                },
                "dataType": "STRING"
            },
            {
                "fieldId": "externalId",
                "fieldAlias": "externalId",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "externalId"
                },
                "dataType": "STRING"
            }
        ],
        "auditInfo": {
            "createdOn": "2025-03-28T13:48:47.665+00:00",
            "createdBy": 75155282,
            "lastUpdatedOn": "2025-03-28T13:48:47.665+00:00",
            "lastUpdatedBy": 75155282
        }
    },
    "errors": []
}

{
    "data": {
        "id": "67ebcbe9730aa850fc504145",
        "orgId": 100737,
        "searchStrategyType": "COMBINATION",
        "entityType": "TRANSACTION",
        "dataFieldDefinitions": [
            {
                "fieldId": "billNumber",
                "fieldAlias": "billNumber",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "billNumber"
                },
                "dataType": "STRING"
            },
            {
                "fieldId": "billDate",
                "fieldAlias": "billDate",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "billDate"
                },
                "dataType": "DATE"
            },
            {
                "fieldId": "storename",
                "fieldAlias": "storename",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "additionalFields.storename"
                },
                "dataType": "STRING"
            },
            {
                "fieldId": "storecode",
                "fieldAlias": "storecode",
                "fieldType": "DATA",
                "dataSourceDetails": {
                    "fieldReference": "additionalFields.storecode"
                },
                "dataType": "STRING"
            }
        ],
        "auditInfo": {
            "createdOn": "2025-04-01T11:20:09.793+00:00",
            "createdBy": 75155282,
            "lastUpdatedOn": "2025-04-01T11:20:09.793+00:00",
            "lastUpdatedBy": 75155282
        }
    },
    "errors": []
}


Error Responses

HTTP StatusError CodeDescription
4001060Data fields already exist for the given org, entity type, and search strategy type
4001053Field is not allowed
4001003Field definitions cannot be empty
4001004Field identifier cannot be empty
4001005Field data source cannot be empty
4001006Field data type cannot be empty
4001045Field type is required
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!