## List values

`GET /v1/catalog-product-property-enums`

Returns the options of a single trade-catalog list property. The `filter[propertyId]` filter is required — the dictionary is read one property at a time.

## Parameters

| Parameter | Type | Req. | Default | Description |
|----------|-----|:-----:|-----------|---------|
| `filter[propertyId]` | number | **yes** | — | Identifier of the owning property from [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties/list). Without it the request is rejected with `400 MISSING_REQUIRED_FILTER` before Bitrix24 is called |
| `filter` | object | no | — | Other filtering conditions.<br>[Filtering syntax](/docs/filtering). Example: `?filter[propertyId]=166&filter[def]=true` |
| `select` | string | no | — | Field selection: `?select=id,value`. Without `select`, all element fields are returned |
| `sort` | string | no | — | Sort field. The `-` prefix means descending: `?sort=-sort` |
| `limit` | number | no | `50` | Number of records (up to 5000) |
| `offset` | number | no | `0` | Offset from the start of the selection |

For `limit > 50`, the response is automatically assembled from several pages on the server side. The maximum is 5000 records per call.

**The end of the selection is signalled by `meta.hasMore`.** Bitrix24 reports the total, so `meta.total` and `meta.hasMore` are trustworthy — an ordinary `while (hasMore) { offset += limit }` loop works. Rare edge case: if no total arrives, the platform substitutes the length of the received window into `meta.total`, so `hasMore` comes back `false` on a full page; compare `data.length` against the page size to be safe.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/catalog-product-property-enums?filter[propertyId]=166&limit=1000" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/catalog-product-property-enums?filter[propertyId]=166&limit=1000" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const params = new URLSearchParams({ 'filter[propertyId]': '166', limit: '1000' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/catalog-product-property-enums?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
const byId = new Map(data.map(item => [String(item.id), item.value]))
console.log(byId.get('116')) // L
```

### JavaScript — OAuth application

```javascript
const params = new URLSearchParams({ 'filter[propertyId]': '166', limit: '1000' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/catalog-product-property-enums?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of options. The element field set — see [Value fields](./fields.md) |
| `meta.total` | number | Number of records matching the filter. When Bitrix24 does not report it, the window length is returned |
| `meta.hasMore` | boolean | Whether more records exist beyond `limit`. Unreliable at the window edge — see the warning above |

The `id` of each element is what a catalog product carries in `propertyNNN.value`:

```
product.propertyNNN.value  →  String(element.id)  →  element.value
```

A property that is not of the list type (`propertyType` other than `L`) has no enumeration: the request returns `200` with an empty `data`, not an error. Access is restricted by the employee's permissions in Bitrix24.

## Response example

```json
{
  "success": true,
  "data": [
    { "id": 110, "propertyId": 166, "value": "XS", "def": false, "sort": 100, "xmlId": null },
    { "id": 112, "propertyId": 166, "value": "S",  "def": false, "sort": 200, "xmlId": null },
    { "id": 114, "propertyId": 166, "value": "M",  "def": false, "sort": 300, "xmlId": null },
    { "id": 116, "propertyId": 166, "value": "L",  "def": false, "sort": 400, "xmlId": null },
    { "id": 118, "propertyId": 166, "value": "XL", "def": false, "sort": 500, "xmlId": null }
  ],
  "meta": {
    "total": 5,
    "hasMore": false
  }
}
```

## Error response example

400 — the required filter is missing:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FILTER",
    "message": "GET /v1/catalog-product-property-enums requires filter fields: propertyId. Example: GET /v1/catalog-product-property-enums?filter[propertyId]=..."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_FILTER` | The request carries no `filter[propertyId]` key. Bitrix24 is not called |
| 400 | `UNKNOWN_FILTER_FIELD` | Filtering by a field the enumeration element does not have. The message lists the available fields |
| 400 | `UNKNOWN_SORT_FIELD` | Sorting by a field the enumeration element does not have. The message lists the available fields |
| 403 | `SCOPE_DENIED` | The API key does not carry the `catalog` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not sent |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**Dictionaries for several properties are fetched with one batch request** — up to 50 sub-calls, one per `propertyId`:

```json
{
  "calls": [
    { "id": "sizes", "entity": "catalog-product-property-enums",
      "action": "list", "params": { "filter": { "propertyId": 166 }, "limit": 1000 } },
    { "id": "colors", "entity": "catalog-product-property-enums",
      "action": "list", "params": { "filter": { "propertyId": 162 }, "limit": 1000 } }
  ]
}
```

A `list` sub-call with a `limit` above 50 leaves the native Bitrix24 batch and runs as a separate sequential request with its own rate-limit unit — see [Batch requests](/docs/batch). So the batch saves round-trips to the Vibecode API, not Bitrix24 quota units; the explicit `limit` is still required (see the completeness warning above).

Data cannot be passed between the sub-calls of one batch, so `propertyId` has to be known up front — from [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties/list). The required-filter check does not extend to batch sub-calls: the caller owns the `params` of each sub-call. Bitrix24 itself does not treat the filter as mandatory — a sub-call without `propertyId` returns the values of every list property of every trade catalog at once, an answer with no size ceiling.

## See also

- [Get a value](/docs/entities/catalog-product-property-enums/get)
- [Search values](/docs/entities/catalog-product-property-enums/search)
- [Value fields](/docs/entities/catalog-product-property-enums/fields)
- [Catalog product properties](/docs/entities/catalog-product-properties)
- [Catalog products](/docs/entities/catalog-products)
- [Filtering syntax](/docs/filtering)
- [Entity reference](/docs/entities-index)