لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/deals.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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 Required Description
Parametertitle Typestring Requiredno DescriptionDeal title
Parameteramount Typenumber Requiredno DescriptionAmount
Parametercurrency Typestring Requiredno DescriptionCurrency. List: GET /v1/currencies
ParameterstageId Typestring Requiredno DescriptionPipeline stage. Standard stages: NEW, PREPARATION, PREPAYMENT_INVOICE, EXECUTING, FINAL_INVOICE, WON, LOSE. A Bitrix24 account can define its own stages; list them with GET /v1/statuses?filter[entityId]=DEAL_STAGE (for another pipeline — DEAL_STAGE_{categoryId}, stages there carry the C{categoryId}: prefix). Before writing, the value is matched exactly against the stage dictionary — a stage that is not in the pipeline is rejected with UNKNOWN_STAGE, and no record is created. An empty value is not checked: the deal is placed in the default stage
ParametercategoryId Typenumber Requiredno DescriptionPipeline ID (0 = main). List: GET /v1/deal-categories
ParametercompanyId Typenumber Requiredno DescriptionCompany ID. Search: GET /v1/companies
ParametercontactId Typenumber Requiredno DescriptionPrimary contact ID. Search: GET /v1/contacts
ParameterassignedById Typenumber Requiredno DescriptionAssigned person ID. Employee list: GET /v1/users
ParametersourceId Typestring Requiredno DescriptionSource. List: GET /v1/statuses?filter[entityId]=SOURCE
ParametersourceDescription Typestring Requiredno DescriptionSource description
Parametercomments Typestring Requiredno DescriptionComment
Parameteropened Typeboolean Requiredno DescriptionAvailable to everyone
ParameterclosedAt Typedatetime Requiredno DescriptionClosing date
Parameterprobability Typenumber Requiredno DescriptionProbability of success (%)
Parameterobservers Typenumber[] Requiredno DescriptionArray of observer IDs. Employee list: GET /v1/users
ParameterufCrm* Typeper field schema Requiredno DescriptionA 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

No field is required, but the body must contain at least one field.

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
Fieldsuccess Typeboolean Descriptiontrue when the deal is created
Fielddata Typeobject DescriptionThe created deal with all fields, including user fields (ufCrm*). All fields — Deal fields
Fielddata.id Typenumber DescriptionID of the created deal
Fielddata.title Typestring DescriptionTitle
Fielddata.amount Typenumber DescriptionAmount
Fielddata.currency Typestring DescriptionCurrency
Fielddata.stageId Typestring DescriptionStage
Fielddata.categoryId Typenumber DescriptionPipeline ID
Fielddata.assignedById Typenumber DescriptionAssigned person
Fielddata.createdBy Typenumber DescriptionCreator
Fielddata.createdAt Typedatetime DescriptionCreation date
Fielddata.updatedAt Typedatetime DescriptionModification date

The main data fields 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
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens
HTTP400 CodeEMPTY_CREATE_BODY DescriptionThe request body is empty — pass at least one field
HTTP400 CodeINVALID_PARAMS DescriptionA field value has the wrong type or format
HTTP400 CodeREADONLY_FIELD DescriptionThe request body contains a read-only field, such as isWon. Such fields are marked in the RO column of Deal fields
HTTP400 CodeUNKNOWN_STAGE DescriptionstageId is not in the stage dictionary of pipeline categoryId (the main pipeline if categoryId is omitted): a typo, wrong letter case, or another pipeline's stage sent without its categoryId. No record is created; message suggests the exact spelling or the categoryId to pass, and details.knownStages lists the dictionary's stages

Full list of common API errors — Errors.

See also