Get label assignments

Time	Status	User Agent
Retrieving recent requests…

Retrieve all label assignments for a set of entities. Pass up to 10 entity IDs in a single request to get each entity's active — and optionally inactive — label assignments.

Example request

curl -X GET "https://{host}/v2/labels/assignments?entityType=CUSTOMER&entityIds=<ENTITY_ID>&includeInactive=false" \
  -H "Authorization: Basic {base64_credentials}"

Prerequisites

Basic authentication (Authorization: Basic {base64_credentials}) or OAuth (X-CAP-API-OAUTH-TOKEN).

Resource information


Pagination support	No
Batch support	Yes — up to 10 entity IDs per request

Query parameters

Field	Type	Required	Description
`entityType`	enum	Required	Entity type to query. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. Case-sensitive.
`entityIds`	string	Required	Comma-separated list of entity IDs to look up. Maximum 10 IDs per request.
`includeInactive`	boolean	Optional	Set to `true` to include expired and inactive assignments in the response. Defaults to `false`.

Example response

{
  "data": [
    {
      "entityId": "<ENTITY_ID>",
      "labels": [
        {
          "labelId": 109,
          "labelName": "Doc Test Label Relative",
          "labelExternalId": "doc-test-relative-001",
          "expiryDate": "2027-06-04T18:29:59Z"
        }
      ]
    }
  ]
}

Response parameters

Field	Type	Description
`data`	array	One entry per requested entity ID.
`.entityId`	string	Identifier of the entity.
`.labels`	array	List of label assignments for the entity. Empty when the entity has no active assignments.
`..labelId`	number	Unique identifier of the label.
`..labelName`	string	Name of the label.
`..labelExternalId`	string	External identifier of the label.
`..expiryDate`	string	Expiry date and time of the assignment in ISO-8601 format. `null` if the assignment does not expire.
`errors`	array	List of request-level errors.

Error and warning codes

Note: Validation errors for this endpoint are returned as {"message": "<error description>"} rather than the standard errors array.

Code	Error number	Type	Description
`ASSIGNMENT_ENTITY_TYPE_REQUIRED`	23033	Error	`entityType` is required. HTTP 400.
`ASSIGNMENT_INVALID_ENTITY_TYPE`	23034	Error	Invalid entity type. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. HTTP 400.
`ASSIGNMENT_ENTITY_IDS_REQUIRED`	23041	Error	`entityIds` must contain at least one value. HTTP 400.
`ASSIGNMENT_ENTITY_IDS_EXCEEDED`	23042	Error	Maximum 10 entity IDs can be queried in a single request. HTTP 400.