For AI agents: markdown of this page — /docs-content-en/entities/crm-forms/results.md documentation index — /llms.txt

Submit visitor data

POST /v1/crm-forms/:id/results

Submits CRM form field values on behalf of a visitor, as when the form is filled in on a website. The result is processed according to the form settings: it can create a lead or deal, trigger automation and send notifications to the responsible persons.

Parameters

Parameter Type Required Description
Parameterid (path) Typeinteger Requiredyes DescriptionForm ID. List: Form list

Request fields (body)

Field Type Required Description
Fieldfields Typeobject Requiredyes DescriptionNon-empty object of values. Keys are form field names fields[].name from Get a form, for example LEAD_NAME, LEAD_PHONE. Fields of type file are not supported
Fieldpresets Typeobject Requiredno DescriptionPreset values, passed unchanged
FieldfromUrl Typestring Requiredno DescriptionURL of the page where the form was filled in

No other fields are accepted in the body. The set and values of fields are validated against the form settings.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-forms/75/results" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"LEAD_NAME":"Anna","LEAD_PHONE":"+12025550123"},"fromUrl":"https://example.com/contact"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-forms/75/results" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"LEAD_NAME":"Anna","LEAD_PHONE":"+12025550123"},"fromUrl":"https://example.com/contact"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/75/results', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: { LEAD_NAME: 'Anna', LEAD_PHONE: '+12025550123' },
    fromUrl: 'https://example.com/contact',
  }),
})

const { data } = await res.json()
console.log('Form result:', data.resultId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-forms/75/results', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: { LEAD_NAME: 'Anna', LEAD_PHONE: '+12025550123' },
    fromUrl: 'https://example.com/contact',
  }),
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the result is saved
Fielddata.resultId Typenumber DescriptionID of the form submission result. This is not the ID of the created lead or deal

Response example

HTTP 201 — the result is saved:

JSON 
{
  "success": true,
  "data": {
    "resultId": 231
  }
}

Error response example

404 — no form with this id:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Form not found."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS Descriptionfields is not passed, is empty or is not an object, message "fields must be a non-empty object"
HTTP400 CodeINVALID_PARAMS Descriptionid is not a positive integer, message "id must be a positive safe integer"
HTTP400 CodeINVALID_PARAMS DescriptionThe body is not a JSON object, message "Request body must be a JSON object"
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field other than fields, presets, fromUrl, message "Only fields, presets and fromUrl are accepted"
HTTP400 CodeINVALID_PARAMS Descriptionpresets is not an object or fromUrl is not a string
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo form with this id, message "Form not found."
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not accept the result: the form is inactive ("Form is not active.") or a field of type file is passed. The Bitrix24 text comes in message and the original code in b24Code (ERROR_CORE for an inactive form)
HTTP403 CodeBitrix24 code DescriptionBitrix24 denied access. code and message come from Bitrix24 unchanged
HTTP409 CodeBitrix24 code DescriptionBitrix24 rejected the result because of the form or portal state. code and message come from Bitrix24 unchanged
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. Submitting requires a key with write access
HTTP429 CodeRATE_LIMITED DescriptionThe Bitrix24 request rate limit is exceeded
HTTP502 CodeBITRIX_RESPONSE_INVALID DescriptionBitrix24 did not return a result ID, message Bitrix24 returned no result ID; do not retry blindly
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable: it responded with a server error or the connection dropped
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the request but did not respond within the allotted time
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope

Full list of common API errors — Errors.

Known specifics

  • Do not retry a submission blindly. Each call saves a new result, and Vibecode does not retry the submission itself. After 502, 503 or a dropped connection, the result may already be saved and may have triggered automation, so a repeated call creates a second result.
  • Unknown fields keys are not rejected. A value with a name that does not exist in the form does not cause an error: the result is created and 201 is returned. Check the keys against the form's fields[].name before submitting.

See also