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
ParameterpresetId (path) Typenumber Requiredyes DescriptionRequisite preset ID

Request fields (body)

Field Type Required Description
FieldfieldName Typestring Requiredyes DescriptionRequisite field identifier — for example, RQ_INN. List of allowed values: GET /v1/requisite-presets/:presetId/fields/available
FieldfieldTitle Typestring Requiredno DescriptionField title in the Bitrix24 interface. If not provided, the system field name is used
FieldinShortList Typeboolean Requiredno DescriptionWhether to show the field in the short list. Accepts true/false
Fieldsort Typenumber Requiredno DescriptionSort 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 application

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 application

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created preset field row. The full field set is returned on a confirmed match, otherwise only id (see "Known specifics")
Fielddata.id Typenumber DescriptionPreset field row identifier
Fielddata.fieldName Typestring DescriptionSystem name of the requisite field: RQ_INN, RQ_COMPANY_NAME, etc. Returned in the full response shape
Fielddata.fieldTitle Typestring DescriptionField title. Returned in the full response shape
Fielddata.inShortList Typeboolean DescriptionWhether it is shown in the short list. Returned in the full response shape
Fielddata.sort Typenumber DescriptionSort 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
HTTP400 CodeINVALID_PRESET_ID DescriptionpresetId is not a positive integer
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope. Message: This endpoint requires 'crm' scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI 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