For AI agents: markdown of this page — /docs-content-en/entities/requisite-presets/preset-fields/create.md documentation index — /llms.txt

Add a field to a preset

POST /v1/requisite-presets/:presetId/fields

Adds a field from the available list to a requisite preset. The list of available fields is returned by GET /v1/requisite-presets/:presetId/fields/available.

Parameters

Parameter Type Required Description
presetId (path) number yes Requisite preset ID

Request fields (body)

Field Type Required Description
fieldName string yes Requisite field identifier — for example, RQ_INN. List of allowed values: GET /v1/requisite-presets/:presetId/fields/available
fieldTitle string no Field title in the Bitrix24 interface. If not provided, the system field name is used
inShortList boolean no Whether to show the field in the short list. Accepts true/false
sort number no Sort order of the field within the preset

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisite-presets/1/fields" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "RQ_CONTACT",
    "inShortList": true,
    "sort": 500
  }'

curl — OAuth app

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/requisite-presets/1/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "RQ_CONTACT",
    "inShortList": true,
    "sort": 500
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisite-presets/1/fields', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fieldName: 'RQ_CONTACT',
    inShortList: true,
    sort: 500,
  }),
})

const { success, data } = await res.json()
console.log('Added field ID:', data.id)

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/requisite-presets/1/fields', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fieldName: 'RQ_CONTACT',
    inShortList: true,
    sort: 500,
  }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data object The created preset field row. The full field set is returned on a confirmed match, otherwise only id (see "Known specifics")
data.id number Preset field row identifier
data.fieldName string System name of the requisite field: RQ_INN, RQ_COMPANY_NAME, etc. Returned in the full response shape
data.fieldTitle string Field title. Returned in the full response shape
data.inShortList boolean Whether it is shown in the short list. Returned in the full response shape
data.sort number Sort order. Returned in the full response shape

Response example

HTTP status: 201 Created

JSON 
{
  "success": true,
  "data": {
    "id": 1,
    "fieldName": "RQ_CONTACT",
    "fieldTitle": "Contact person",
    "inShortList": true,
    "sort": 500
  }
}

Response example — identifier only

When the fieldName match cannot be confirmed, only the identifier is returned:

JSON 
{
  "success": true,
  "data": {
    "id": 1
  }
}

Error response example

400 — invalid presetId:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PRESET_ID",
    "message": "presetId must be a positive integer"
  }
}

Errors

HTTP Code Description
400 INVALID_PRESET_ID presetId is not a positive integer
403 SCOPE_DENIED API key lacks the crm scope. Message: This endpoint requires 'crm' scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

The response comes in one of two shapes. After creation Vibecode re-reads the row and compares its fieldName with the one requested. On a match it returns the full row — id, fieldName, fieldTitle, inShortList, sort. If the match cannot be confirmed, only id is returned. If you get a response with id only, re-read the list of preset fields and find the row by fieldName before updating or deleting it.

See also