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

Create deal

POST /v1/deals

Creates a new deal in the 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
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

Full list of fields: GET /v1/deals/fields. User fields (ufCrm_*) are also accepted.

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 app

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 app

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
entityTypeId number Entity type (2 = deals)

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 account 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": [],
    "entityTypeId": 2
  }
}

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

Full list of common API errors — Errors.

See also