## Dictionary fields

`GET /v1/statuses/fields`

Returns a description of all entity fields with their types and attributes.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/statuses/fields" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/statuses/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/fields', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/statuses/fields', {
  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.fields` | object | Map of record fields. The key is the field name in camelCase, as in API responses, and the value is its description |
| `data.fields.<field>.type` | string | Value type: `number`, `string`, `boolean`, `object` |
| `data.fields.<field>.readonly` | boolean | Read-only field |
| `data.fields.<field>.label` | string | Field label |
| `data.fields.<field>.description` | string | Field description |
| `data.batch` | string[] | Write operations available to the dictionary in the batch call `POST /v1/statuses/batch`: `create`, `update`, `delete` — see [Batch calls](/docs/batch) |

The `label` and `description` values are returned in English. Request headers do not switch the language.

Dictionary record fields described by `data.fields`:

| Field | Type | RO | Description |
|------|-----|:--:|---------|
| `id` | number | yes | Record ID |
| `entityId` | string | | Dictionary type (DEAL_STAGE, SOURCE, etc.). Set only when [creating a record](/docs/entities/statuses/create). `PATCH` does not change it |
| `statusId` | string | | Symbolic code of the value. Set only when [creating a record](/docs/entities/statuses/create). `PATCH` does not change it |
| `name` | string | | Name |
| `nameInit` | string/null | | Original name |
| `description` | string/null | | Record description. Not returned on every Bitrix24 account. Where it is missing, the field arrives as `null` |
| `sort` | number | | Sort order |
| `color` | string/null | | Color in HEX with a leading `#` |
| `semantics` | string/null | | Semantics: `S` — success, `F` — failure. `null` — an in-progress stage or a dictionary without semantics. Set only when [creating a record](/docs/entities/statuses/create). `PATCH` does not change it |
| `system` | boolean | yes | System value that cannot be changed or deleted |
| `categoryId` | number/null | | Pipeline ID. Populated for dictionaries of the form `DEAL_STAGE_N`, otherwise `0` or `null`. Determined by the dictionary in `entityId`, `PATCH` does not change it |
| `extra` | object | yes | Additional data for dictionaries with stages — `STATUS`, `DEAL_STAGE`, `DEAL_STAGE_N`, `QUOTE_STATUS`. Contains the nested keys `SEMANTICS` and `COLOR`. Other dictionaries do not have this field |

## Response example

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Unique numeric identifier of the reference-book entry." },
      "entityId": { "type": "string", "readonly": false, "label": "Reference type", "description": "Reference-book type this entry belongs to (e.g. DEAL_STAGE, SOURCE, STATUS)." },
      "statusId": { "type": "string", "readonly": false, "label": "Status code", "description": "Symbolic code of the value within its reference book." },
      "name": { "type": "string", "readonly": false, "label": "Name", "description": "Display name of the entry." },
      "nameInit": { "type": "string", "readonly": false, "label": "Initial name", "description": "Original name assigned when the entry was created." },
      "description": { "type": "string", "readonly": false, "label": "Description", "description": "Text description of the entry. The field is not available on every Bitrix24 account." },
      "sort": { "type": "number", "readonly": false, "label": "Sort", "description": "Sort order within the reference book." },
      "color": { "type": "string", "readonly": false, "label": "Color", "description": "HEX color of the value." },
      "semantics": { "type": "string", "readonly": false, "label": "Semantics", "description": "Stage semantics: S — success, F — failure, null — in progress or no semantics." },
      "system": { "type": "boolean", "readonly": true, "label": "System", "description": "System value that cannot be changed or deleted." },
      "categoryId": { "type": "number", "readonly": false, "label": "Pipeline ID", "description": "Pipeline ID for entityId values of the DEAL_STAGE_N form." },
      "extra": { "type": "object", "readonly": true, "label": "Extra data", "description": "Additional data of stage directories — an object with the nested keys SEMANTICS (stage semantics) and COLOR (stage colour). Filled by Bitrix24, read-only." }
    },
    "batch": ["create", "update", "delete"]
  }
}
```

## Error response example

403 — missing scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | API key does not have the `crm` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header |

For the full list of errors, see [Errors](/docs/errors).

## Known specifics

**The `SEMANTICS` key inside `extra` is more detailed than the `semantics` field.** The field distinguishes three states, while the nested key distinguishes four. The mapping below holds for a stage whose `sort` places it within its own group:

| `extra.SEMANTICS` | `semantics` | Stage state |
|-------------------|-------------|-------------|
| `process` | `null` | Intermediate stage |
| `success` | `S` | Successful completion |
| `failure` | `F` | Failure |
| `apology` | `F` | Another final failure stage |

The `failure` and `apology` stages are indistinguishable in the `semantics` field — both arrive as `F`. If your scenario needs to tell them apart, read `extra.SEMANTICS`.

**`extra.SEMANTICS` follows `sort`, while `semantics` does not.** The nested key is computed from the stage position relative to the success stage: a stage with `semantics: "F"` placed before the success stage by `sort` returns `extra.SEMANTICS: "process"`, while the `semantics` field stays `F`. So changing `sort` does not change the stage group. To replace a stage with one from another group, see [Update dictionary record](/docs/entities/statuses/update).

## See also

- [CRM dictionaries](/docs/entities/statuses)
- [List of dictionaries](/docs/entities/statuses/list)