## Recurring deal fields `GET /v1/recurring-deals/fields` Returns field definitions for deal recurrence settings. Use it to check types, required fields and whether a field can be written. ## Parameters | Parameter | Type | Default | Description | |---|---|---|---| | `refresh` (query) | string | `false` | Supply `true` to refresh field metadata, for example `?refresh=true` | ## Examples ### curl — personal key ```bash curl -X GET "https://vibecode.bitrix24.com/v1/recurring-deals/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl -X GET "https://vibecode.bitrix24.com/v1/recurring-deals/fields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — personal key ```javascript const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals/fields', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_API_KEY' }, }) const result = await response.json() if (!result.success) throw new Error(result.error.message) console.log(result.data) ``` ### JavaScript — OAuth application ```javascript const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals/fields', { method: 'GET', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' }, }) const result = await response.json() if (!result.success) throw new Error(result.error.message) console.log(result.data) ``` ## Response fields | Field | Type | Description | |---|---|---| | `success` | boolean | Whether the request succeeded | | `data.fields` | object | Complete field definitions: type, `readonly`, `required`, `createOnly`, `nullable`, `enum`, `properties` when present | | `data.batch` | string[] | Entity operations listed for batch processing: `create`, `update`, `delete` | | `meta.warnings` | object[] | A `fields_partial` warning may be returned when field definitions are partially loaded | | Field | Type | RO | Description | |---|---|---|---| | `id` | number | Yes | Setting ID. See [get a setting](./get.md). | | `dealId` | number | No | Template deal ID. Required and writable only on creation. A regular source deal is copied. See the [deal](/docs/entities/deals/get). | | `basedId` | number | Yes | Source deal ID. See the [deal](/docs/entities/deals/get). May be `null`. | | `active` | boolean | No | Whether automatic recurrence is active | | `nextExecution` | datetime | Yes | Next execution date. May be `null`. | | `lastExecution` | datetime | Yes | Last execution date. May be `null`. | | `counterRepeat` | number | Yes | Execution count. May be `null`. | | `startDate` | date | No | Schedule start date. May be `null`. | | `categoryId` | number | No | Pipeline for created deals. See the [pipeline](/docs/entities/deal-categories/get). May be `null`. | | `isLimit` | string | No | Limit mode: `N` — unlimited, `T` — repetition count, `D` — end date | | `limitRepeat` | number | No | Maximum repetitions in mode `T`. May be `null`. | | `limitDate` | date | No | Last allowed date in mode `D`. May be `null`. | | `params` | object | No | Complete schedule parameters. Replaced in full on update | | `params.mode` | string | No | Schedule mode. May be `null`. | | `params.singleBeforeStartDateValue` | number | No | Single execution offset value | | `params.singleBeforeStartDateType` | string | No | Single execution offset type. May be `null`. | | `params.multipleType` | string | No | Recurrence period type. May be `null`. | | `params.multipleInterval` | number | No | Recurrence interval | | `params.offsetBeginDateType` | string | No | Start date offset type. May be `null`. | | `params.offsetBeginDateValue` | number | No | Start date offset value | | `params.offsetCloseDateType` | string | No | End date offset type. May be `null`. | | `params.offsetCloseDateValue` | number | No | End date offset value | `RO` means the field is read-only. ## Response example ```json { "success": true, "data": { "fields": { "id": { "type": "number", "readonly": true, "label": "Recurring settings ID", "description": "Recurring settings ID." }, "dealId": { "type": "number", "readonly": false, "createOnly": true, "required": true, "label": "Template deal ID; ordinary source deals are copied on creation", "description": "Template deal ID; ordinary source deals are copied on creation." }, "basedId": { "type": "number", "readonly": true, "nullable": true, "label": "Source deal ID", "description": "Source deal ID." }, "active": { "type": "boolean", "readonly": false, "label": "Whether automatic repetition is active", "description": "Whether automatic repetition is active." }, "nextExecution": { "type": "datetime", "readonly": true, "nullable": true, "label": "Next execution date", "description": "Next execution date." }, "lastExecution": { "type": "datetime", "readonly": true, "nullable": true, "label": "Last execution date", "description": "Last execution date." }, "counterRepeat": { "type": "number", "readonly": true, "nullable": true, "label": "Executed repetitions", "description": "Executed repetitions." }, "startDate": { "type": "date", "readonly": false, "nullable": true, "label": "Schedule start date", "description": "Schedule start date." }, "categoryId": { "type": "number", "readonly": false, "nullable": true, "label": "Pipeline for newly generated deals", "description": "Pipeline for newly generated deals." }, "isLimit": { "type": "string", "readonly": false, "label": "Repetition limit mode", "description": "Repetition limit mode.", "enum": [ { "value": "N", "label": "Unlimited" }, { "value": "T", "label": "Repetition count" }, { "value": "D", "label": "End date" } ] }, "limitRepeat": { "type": "number", "readonly": false, "nullable": true, "label": "Maximum repetition count for T", "description": "Maximum repetition count for T." }, "limitDate": { "type": "date", "readonly": false, "nullable": true, "label": "Last allowed date for D", "description": "Last allowed date for D." }, "params": { "type": "object", "readonly": false, "label": "Complete schedule parameters; replace as a whole on update", "description": "Complete schedule parameters; replace as a whole on update.", "properties": { "mode": { "type": "string", "nullable": true }, "singleBeforeStartDateValue": { "type": "number" }, "singleBeforeStartDateType": { "type": "string", "nullable": true }, "multipleType": { "type": "string", "nullable": true }, "multipleInterval": { "type": "number" }, "offsetBeginDateType": { "type": "string", "nullable": true }, "offsetBeginDateValue": { "type": "number" }, "offsetCloseDateType": { "type": "string", "nullable": true }, "offsetCloseDateValue": { "type": "number" } } } }, "batch": [ "create", "update", "delete" ] } } ``` ## Error response example 401 — API key missing: ```json { "success": false, "error": { "code": "MISSING_API_KEY", "message": "API key required. Pass via X-Api-Key header." } } ``` ## Errors | HTTP | Code | Description | |---|---|---| | 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing | | 401 | `TOKEN_MISSING` | No Bitrix24 access tokens are configured | | 403 | `SCOPE_DENIED` | The API key lacks the `crm` scope | | 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access, including a missing required scope | | 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation or a plan restriction applies. See `error.message` | | 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. Retry after the interval in `Retry-After` | | 502 | `BITRIX_UNAVAILABLE` | A connection to Bitrix24 could not be established | | 429 | `RATE_LIMITED` | The request rate limit was exceeded. The effective limit is in the `x-ratelimit-limit` header. Retry after the interval in the `Retry-After` header | For the full list of common API errors, see [Error codes](/docs/errors). ## See also - [List recurring deals](./list.md) - [Get a recurring deal](./get.md) - [Search recurring deals](./search.md) - [Aggregate recurring deals](./aggregate.md) - [Recurring deals](../recurring-deals.md) - [Filtering syntax](/docs/filtering)