Per gli agenti AI: markdown di questa pagina — /docs-content-en/entities/deals.md indice della documentazione — /llms.txt

Gli articoli della documentazione sono attualmente disponibili solo in inglese.

Deals

CRM deal management: create, retrieve, update, delete, filter.

Bitrix24 API: crm.item.* Scope: crm

Create deal

POST /v1/deals

Creates a new deal in CRM.

Request fields (body)

Parameter Type Description
title string Deal title
amount number Amount
currency string Currency. List: GET /v1/currencies
stageId string Pipeline stage. Standard: NEW, PREPARATION, PREPAYMENT_INVOICE, EXECUTING, FINAL_INVOICE, WON, LOSE. A Bitrix24 account may have its own — list: GET /v1/statuses?filter[entityId]=DEAL_STAGE (for another pipeline — DEAL_STAGE_{categoryId}, stages there carry the C{categoryId}: prefix). Checked literally against the dictionary before the write — a stage the pipeline does not have is refused with UNKNOWN_STAGE, no record is created. An empty value is not checked: the deal lands on the default stage
categoryId number Pipeline ID (0 = main). List: GET /v1/deal-categories
companyId number Company ID. Search: GET /v1/companies
contactId number Primary contact ID. Search: GET /v1/contacts
assignedById number Assigned person ID. Employee list: GET /v1/users
sourceId string Source. List: GET /v1/statuses?filter[entityId]=SOURCE
sourceDescription string Source description
comments string Comment
opened boolean Available to everyone
closedAt datetime Closing date
probability number Probability of success (%)
observers number[] Array of observer IDs. Employee list: GET /v1/users
ufCrm* per field schema A user field of the Bitrix24 account, for example ufCrmProjectCode. The actual name and type are in the schema GET /v1/deals/fields, and the value format for each type is in User fields (UF). An enumeration field takes the option ID from the field's items array in the schema, and a multiple field takes an array of such IDs. If you send the option label VALUE instead of the ID, the value is lost: a single-value field gets 0. A number that is not among the options is stored as is. Neither the label nor a non-existent ID raises an error, and the request returns 201, so map the label to its ID on your side and check the stored value of this field in the response data

Full list of fields: GET /v1/deals/fields.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/deals \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Equipment delivery",
    "amount": 50000,
    "currency": "USD",
    "stageId": "NEW",
    "categoryId": 0,
    "assignedById": 1
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/deals \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Equipment delivery",
    "amount": 50000,
    "currency": "USD",
    "stageId": "NEW",
    "categoryId": 0,
    "assignedById": 1
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Equipment delivery',
    amount: 50000,
    currency: 'USD',
    stageId: 'NEW',
    categoryId: 0,
    assignedById: 1,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/deals', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Equipment delivery',
    amount: 50000,
    currency: 'USD',
    stageId: 'NEW',
    categoryId: 0,
    assignedById: 1,
  }),
})

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

Response fields

Field Type Description
id number ID of the created deal
title string Title
amount number Amount
currency string Currency
stageId string Stage
categoryId number Pipeline ID
assignedById number Assigned person
createdBy number Creator
createdAt datetime Creation date
updatedAt datetime Modification date

The response contains all deal fields, including user fields (ufCrm*). The main ones are shown above.

The deal card URL in Bitrix24 is built from id:

https://<portal>.bitrix24.com/crm/deal/details/<id>/

<portal> — the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 7689,
    "title": "Equipment delivery",
    "amount": 50000,
    "currency": "USD",
    "stageId": "NEW",
    "categoryId": 0,
    "assignedById": 1,
    "createdBy": 1,
    "createdAt": "2026-04-14T08:43:59.000Z",
    "updatedAt": "2026-04-14T08:43:59.000Z",
    "companyId": 0,
    "contactId": 0,
    "opened": true,
    "closed": false,
    "typeId": "SALE",
    "observers": [],
    "contactIds": []
  }
}

Error response example

403 — no scope:

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

Errors

HTTP Code Description
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens
400 INVALID_REQUEST Invalid fields
400 READONLY_FIELD The request body contains a read-only field, such as isWon. Such fields are marked in the RO column of Deal fields
400 UNKNOWN_STAGE stageId is not in the stage dictionary of pipeline categoryId (without it — the main one): a typo, a different letter case, another pipeline's stage without its categoryId. No record is created; message suggests the exact spelling or the categoryId to pass, details.knownStages lists the dictionary's stages

Full list of common API errors — Errors.

See also