Search label assignments

Time	Status	User Agent
Retrieving recent requests…

Search label assignments by a specific label, with optional filtering by entity ID and pagination. Use this endpoint to find which entities have a particular label assigned.

Example request

curl -X GET "https://{host}/v2/labels/assignments/search?entityType=CUSTOMER&labelId=109&limit=10&offset=0" \
  -H "Authorization: Basic {base64_credentials}"

Prerequisites

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

Resource information


Pagination support	Yes
Batch support	No

Query parameters

Field	Type	Required	Description
`entityType`	enum	Required	Entity type to search within. Supported values: `CUSTOMER`, `PRODUCT`, `STORE`. Case-sensitive.
`labelId`	number	Conditional	Unique identifier of the label to search by. Provide exactly one of `labelId`, `labelName`, or `labelExternalId`.
`labelName`	string	Conditional	Name of the label to search by. Provide exactly one of `labelId`, `labelName`, or `labelExternalId`.
`labelExternalId`	string	Conditional	External identifier of the label to search by. Provide exactly one of `labelId`, `labelName`, or `labelExternalId`.
`entityId`	string	Optional	Filters results to a specific entity ID.
`limit`	number	Optional	Maximum number of results to return per page. Between 1 and 50. Defaults to 10.
`offset`	number	Optional	Number of records to skip for pagination. Must be 0 or greater. Defaults to 0.

Example response

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

Response parameters

Field	Type	Description
`data`	array	List of label assignment records matching the search criteria.
`.entityId`	string	Identifier of the entity.
`.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.
`pagination`	object	Pagination metadata.
`.totalCount`	number	Total number of matching records.
`.limit`	number	Maximum number of records returned in this response.
`.offset`	number	Number of records skipped.

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_LABEL_SEARCH_IDENTIFIER_REQUIRED`	23036	Error	Exactly one of `labelId`, `labelName`, or `labelExternalId` is required. HTTP 400.
`ASSIGNMENT_INVALID_LIMIT`	23046	Error	`limit` must be between 1 and 50. HTTP 400.
`ASSIGNMENT_INVALID_OFFSET`	23047	Error	`offset` must be 0 or greater. HTTP 400.