Create a New Deal crm.deal.add

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

Scope: crm

Who can execute the method: any user with "add" access permission for deals

DEPRECATED

The development of this method has been halted. Please use crm.item.add.

The method crm.deal.add creates a new deal.

Method Parameters

Name
type

Description

fields
object

Object format:

{
            field_1: value_1,
            field_2: value_2,
            ...,
            field_n: value_n,
        }
        

where:

  • field_n — field name
  • value_n — field value

The list of available fields is described below

params
object

Object containing an additional set of parameters (detailed description)

Parameter fields

Name
type

Description

TITLE
string

Deal title.

By default, it is generated using the template Deal #{id}, where id is the element identifier

TYPE_ID
crm_status

String identifier of the deal type.

The list of available deal types can be obtained using the method crm.status.list with the filter { ENTITY_ID: 'DEAL_TYPE' }.

By default — the first available deal type

CATEGORY_ID
crm_category

Funnel identifier. Must be greater than or equal to 0.

The list of available funnels can be obtained using the method crm.category.list by passing entityTypeId = 2.

By default — the default funnel identifier

STAGE_ID
crm_status

Deal stage.

The list of available stages can be obtained using the method crm.status.list with the filter:

  • { ENTITY_ID: "DEAL_STAGE" } — if the deal is in the general funnel (direction)
  • { ENTITY_ID: "DEAL_STAGE_{categoryId}" } — if the deal is not in the general funnel, where categoryId is the identifier of the deal funnel

By default — the first available stage relative to the funnel

IS_RECURRING
char

Indicates whether the deal is a template for a recurring deal. Possible values:

  • Y — yes
  • N — no

By default N

IS_RETURN_CUSTOMER
char

Indicates whether the deal is a repeat. Possible values:

  • Y — yes
  • N — no

By default N

IS_REPEATED_APPROACH
char

Indicates whether the deal is a repeated approach. Possible values:

  • Y — yes
  • N — no

By default N

PROBABILITY
integer

Probability, %

CURRENCY_ID
crm_currency

Currency.

The list of available currencies can be obtained using the method crm.currency.list

OPPORTUNITY
double

Amount.

By default 0.00

IS_MANUAL_OPPORTUNITY
char

Indicates whether manual calculation of the amount is enabled. Possible values:

  • Y — yes
  • N — no

By default N

TAX_VALUE
double

Tax amount.

By default 0.00

COMPANY_ID
crm_company

Identifier of the company associated with the deal.

The list of companies can be obtained using the method crm.item.list by passing entityTypeId = 4

CONTACT_ID
crm_contact

Contact. Deprecated

CONTACT_IDS
crm_contact[]

List of contacts associated with the deal.

The list of contacts can be obtained using the method crm.item.list by passing entityTypeId = 3

BEGINDATE
date

Start date.

By default — the date the deal is created

CLOSEDATE
date

Close date.

By default — the date the deal is created plus 7 days

OPENED
char

Is the deal available to everyone? Possible values:

  • Y — yes
  • N — no

By default Y. The default value can be changed in the CRM settings

CLOSED
char

Is the deal closed? Possible values:

  • Y — yes
  • N — no

By default N

COMMENTS
string

Comment. Supports bb-codes

ASSIGNED_BY_ID
user

Responsible person.

By default — the user calling this method

SOURCE_ID
crm_status

String identifier of the source type.

The list of available sources can be obtained using the method crm.status.list with the filter { ENTITY_ID: "SOURCE" }.

By default — the first available source type

SOURCE_DESCRIPTION
string

Additional information about the source

ADDITIONAL_INFO
string

Additional information

LOCATION_ID
location

Client's location. System field

ORIGINATOR_ID
string

Identifier of the data source.

Used only for linking to an external source

ORIGIN_ID
string

Identifier of the element in the data source.

Used only for linking to an external source

UTM_SOURCE
string

Advertising system (Google-Adwords and others)

UTM_MEDIUM
string

Traffic type. Possible values:

  • CPC — ads
  • CPM — banners

UTM_CAMPAIGN
string

Advertising campaign designation

UTM_CONTENT
string

Campaign content. For example, for contextual ads

UTM_TERM
string

Campaign search term. For example, keywords for contextual advertising

TRACE
string

Information for Sales Intelligence — read more in the article How to pass data to Sales Intelligence

UF_CRM_...

Custom fields. For example, UF_CRM_25534736.

Depending on the portal settings, deals may have a set of custom fields of specific types.

You can add a custom field to a deal using the method crm.deal.userfield.add

PARENT_ID_...
crm_entity

Relationship fields.

If there are smart processes related to deals on the portal, each such smart process has a field that stores the relationship between this smart process and the deal. The field itself stores the identifier of the element of that smart process.

For example, the field PARENT_ID_153 — relationship with the smart process entityTypeId=153, stores the identifier of the element of this smart process related to the current deal

Parameter params

Name
type

Description

REGISTER_SONET_EVENT
boolean

Should the event of adding a deal be registered in the activity stream? Possible values:

  • Y — yes
  • N — no

By default Y

Code Examples

How to Use Examples in Documentation

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"FIELDS":{"TITLE":"New Deal #1","TYPE_ID":"COMPLEX","CATEGORY_ID":0,"STAGE_ID":"PREPARATION","IS_RECURRING":"N","IS_RETURN_CUSTOMER":"Y","IS_REPEATED_APPROACH":"Y","PROBABILITY":99,"CURRENCY_ID":"EUR","OPPORTUNITY":1000000,"IS_MANUAL_OPPORTUNITY":"Y","TAX_VALUE":0.10,"COMPANY_ID":9,"CONTACT_IDS":[84,83],"BEGINDATE":"'"$(date --iso-8601=seconds)"'","CLOSEDATE":"'"$(date --iso-8601=seconds --date='+10 days')"'", "OPENED":"Y","CLOSED":"N","COMMENTS":"Example comment","SOURCE_ID":"CALLBACK","SOURCE_DESCRIPTION":"Additional information about the source","ADDITIONAL_INFO":"Additional information","UTM_SOURCE":"google","UTM_MEDIUM":"CPC","PARENT_ID_1220":22,"UF_CRM_1721244482250":"Hello World!"},"PARAMS":{"REGISTER_SONET_EVENT":"N"}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"FIELDS":{"TITLE":"New Deal #1","TYPE_ID":"COMPLEX","CATEGORY_ID":0,"STAGE_ID":"PREPARATION","IS_RECURRING":"N","IS_RETURN_CUSTOMER":"Y","IS_REPEATED_APPROACH":"Y","PROBABILITY":99,"CURRENCY_ID":"EUR","OPPORTUNITY":1000000,"IS_MANUAL_OPPORTUNITY":"Y","TAX_VALUE":0.10,"COMPANY_ID":9,"CONTACT_IDS":[84,83],"BEGINDATE":"'"$(date --iso-8601=seconds)"'","CLOSEDATE":"'"$(date --iso-8601=seconds --date='+10 days')"'", "OPENED":"Y","CLOSED":"N","COMMENTS":"Example comment","SOURCE_ID":"CALLBACK","SOURCE_DESCRIPTION":"Additional information about the source","ADDITIONAL_INFO":"Additional information","UTM_SOURCE":"google","UTM_MEDIUM":"CPC","PARENT_ID_1220":22,"UF_CRM_1721244482250":"Hello World!"},"PARAMS":{"REGISTER_SONET_EVENT":"N"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.deal.add
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        const day = 60 * 60 * 24 * 1000
        
        const now = new Date()
        const after10Days = new Date(now.getTime() + 10 * day)
        
        try {
          const response = await $b24.actions.v2.call.make<number>({
            method: 'crm.deal.add',
            params: {
              fields: {
                TITLE: 'New deal #1',
                TYPE_ID: 'COMPLEX',
                CATEGORY_ID: 0,
                STAGE_ID: 'PREPARATION',
                IS_RECURRING: 'N',
                IS_RETURN_CUSTOMER: 'Y',
                IS_REPEATED_APPROACH: 'Y',
                PROBABILITY: 99,
                CURRENCY_ID: 'EUR',
                OPPORTUNITY: 1000000,
                IS_MANUAL_OPPORTUNITY: 'Y',
                TAX_VALUE: 0.10,
                COMPANY_ID: 9,
                CONTACT_IDS: [84, 83],
                BEGINDATE: now.toISOString(),
                CLOSEDATE: after10Days.toISOString(),
                OPENED: 'Y',
                CLOSED: 'N',
                COMMENTS: '[B]Sample comment[/B]',
                SOURCE_ID: 'CALLBACK',
                SOURCE_DESCRIPTION: 'Additional information about the source',
                ADDITIONAL_INFO: 'Additional information',
                UTM_SOURCE: 'google',
                UTM_MEDIUM: 'CPC',
                PARENT_ID_1220: 22,
                UF_CRM_1721244482250: 'Hello world!',
              },
              params: {
                REGISTER_SONET_EVENT: 'N',
              },
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Created deal id:', result)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function addDeal() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const day = 60 * 60 * 24 * 1000
        
              const now = new Date()
              const after10Days = new Date(now.getTime() + 10 * day)
        
              const response = await $b24.actions.v2.call.make({
                method: 'crm.deal.add',
                params: {
                  fields: {
                    TITLE: 'New deal #1',
                    TYPE_ID: 'COMPLEX',
                    CATEGORY_ID: 0,
                    STAGE_ID: 'PREPARATION',
                    IS_RECURRING: 'N',
                    IS_RETURN_CUSTOMER: 'Y',
                    IS_REPEATED_APPROACH: 'Y',
                    PROBABILITY: 99,
                    CURRENCY_ID: 'EUR',
                    OPPORTUNITY: 1000000,
                    IS_MANUAL_OPPORTUNITY: 'Y',
                    TAX_VALUE: 0.10,
                    COMPANY_ID: 9,
                    CONTACT_IDS: [84, 83],
                    BEGINDATE: now.toISOString(),
                    CLOSEDATE: after10Days.toISOString(),
                    OPENED: 'Y',
                    CLOSED: 'N',
                    COMMENTS: '[B]Sample comment[/B]',
                    SOURCE_ID: 'CALLBACK',
                    SOURCE_DESCRIPTION: 'Additional information about the source',
                    ADDITIONAL_INFO: 'Additional information',
                    UTM_SOURCE: 'google',
                    UTM_MEDIUM: 'CPC',
                    PARENT_ID_1220: 22,
                    UF_CRM_1721244482250: 'Hello world!',
                  },
                  params: {
                    REGISTER_SONET_EVENT: 'N',
                  },
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Created deal id:', result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', addDeal)
        </script>
        

        from b24pysdk.errors import BitrixAPIError, BitrixSDKException
        
        try:
            bitrix_response = client.crm.deal.add(
                fields={
                    "TITLE": "Enterprise License Renewal",
                    "TYPE_ID": "SALE",
                    "CATEGORY_ID": 0,
                    "STAGE_ID": "NEW",
                    "CURRENCY_ID": "USD",
                    "OPPORTUNITY": 25000,
                    "IS_MANUAL_OPPORTUNITY": "Y",
                    "ASSIGNED_BY_ID": 1,
                    "OPENED": "Y",
                    "COMMENTS": "Renewal negotiation in progress",
                    "SOURCE_ID": "WEB",
                    "UTM_SOURCE": "google",
                    "UTM_MEDIUM": "cpc",
                    "UTM_CAMPAIGN": "q2_pipeline",
                },
                params={"REGISTER_SONET_EVENT": "Y"},
            ).response
            result = bitrix_response.result
            print(result)
        except BitrixAPIError as error:
            print(
                "Bitrix API error",
                f"error: {error.error}",
                f"error_description: {error.error_description}",
                sep="\n",
            )
        except BitrixSDKException as error:
            print(f"Bitrix SDK error: {error.message}")
        except Exception as error:
            print(f"Unexpected error: {error}")
        
try {
            $fields = [
                'TITLE' => 'New Deal',
                'TYPE_ID' => 'GIG',
                'CATEGORY_ID' => '1',
                'STAGE_ID' => 'C1:NEW',
                'CURRENCY_ID' => 'USD',
                'OPPORTUNITY' => '10000',
                'BEGINDATE' => (new DateTime())->format(DateTime::ATOM),
                'CLOSEDATE' => (new DateTime('+1 month'))->format(DateTime::ATOM),
                'COMMENTS' => 'This is a test deal.',
            ];
            $params = [
                'REGISTER_SONET_EVENT' => 'Y',
            ];
            $result = $serviceBuilder
                ->getCRMScope()
                ->deal()
                ->add($fields, $params);
            print($result->getId());
        } catch (Throwable $e) {
            print('Error: ' . $e->getMessage());
        }
        
const day = 60 * 60 * 24 * 1000;
        
        const now = new Date();
        const after10Days = new Date(now.getTime() + 10 * day);
        
        BX24.callMethod(
            'crm.deal.add',
            {
                fields: {
                    TITLE: "New Deal #1",
                    TYPE_ID: "COMPLEX",
                    CATEGORY_ID: 0,
                    STAGE_ID: "PREPARATION",
                    IS_RECURRING: "N",
                    IS_RETURN_CUSTOMER: "Y",
                    IS_REPEATED_APPROACH: "Y",
                    PROBABILITY: 99,
                    CURRENCY_ID: "EUR",
                    OPPORTUNITY: 1000000,
                    IS_MANUAL_OPPORTUNITY: "Y",
                    TAX_VALUE: 0.10,
                    COMPANY_ID: 9,
                    CONTACT_IDS: [84, 83],
                    BEGINDATE: now.toISOString(),
                    CLOSEDATE: after10Days.toISOString(),
                    OPENED: "Y",
                    CLOSED: "N",
                    COMMENTS: "[B]Example comment[/B]",
                    SOURCE_ID: "CALLBACK",
                    SOURCE_DESCRIPTION: "Additional information about the source",
                    ADDITIONAL_INFO: "Additional information",
                    UTM_SOURCE: "google",
                    UTM_MEDIUM: "CPC",
                    PARENT_ID_1220: 22,
                    UF_CRM_1721244482250: "Hello World!",
                },
                params: {
                    REGISTER_SONET_EVENT: "N",
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data())
                ;
            },
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.deal.add',
            [
                'FIELDS' => [
                    'TITLE' => 'New Deal #1',
                    'TYPE_ID' => 'COMPLEX',
                    'CATEGORY_ID' => 0,
                    'STAGE_ID' => 'PREPARATION',
                    'IS_RECURRING' => 'N',
                    'IS_RETURN_CUSTOMER' => 'Y',
                    'IS_REPEATED_APPROACH' => 'Y',
                    'PROBABILITY' => 99,
                    'CURRENCY_ID' => 'EUR',
                    'OPPORTUNITY' => 1000000,
                    'IS_MANUAL_OPPORTUNITY' => 'Y',
                    'TAX_VALUE' => 0.10,
                    'COMPANY_ID' => 9,
                    'CONTACT_IDS' => [84, 83],
                    'BEGINDATE' => (new DateTime())->format(DateTime::ATOM),
                    'CLOSEDATE' => (new DateTime('+10 days'))->format(DateTime::ATOM),
                    'OPENED' => 'Y',
                    'CLOSED' => 'N',
                    'COMMENTS' => 'Example comment',
                    'SOURCE_ID' => 'CALLBACK',
                    'SOURCE_DESCRIPTION' => 'Additional information about the source',
                    'ADDITIONAL_INFO' => 'Additional information',
                    'UTM_SOURCE' => 'google',
                    'UTM_MEDIUM' => 'CPC',
                    'PARENT_ID_1220' => 22,
                    'UF_CRM_1721244482250' => 'Hello World!',
                ],
                'PARAMS' => [
                    'REGISTER_SONET_EVENT' => 'N',
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        
// client and ctx are already created — see the Go SDK section
        res, err := client.Core().Call(ctx, "crm.deal.add", b24.Params{
        	"fields": b24.Params{
        		"TITLE":                 "New Deal #1",
        		"TYPE_ID":               "COMPLEX",
        		"CATEGORY_ID":           0,
        		"STAGE_ID":              "PREPARATION",
        		"IS_RECURRING":          "N",
        		"IS_RETURN_CUSTOMER":    "Y",
        		"IS_REPEATED_APPROACH":  "Y",
        		"PROBABILITY":           99,
        		"CURRENCY_ID":           "EUR",
        		"OPPORTUNITY":           1000000,
        		"IS_MANUAL_OPPORTUNITY": "Y",
        		"TAX_VALUE":             0.10,
        		"COMPANY_ID":            9,
        		"CONTACT_IDS":           []int{84, 83},
        		"BEGINDATE":             time.Now().Format(time.RFC3339),
        		"CLOSEDATE":             time.Now().AddDate(0, 0, 10).Format(time.RFC3339),
        		"OPENED":                "Y",
        		"CLOSED":                "N",
        		"COMMENTS":              "Example comment",
        		"SOURCE_ID":             "CALLBACK",
        		"SOURCE_DESCRIPTION":    "Additional information about the source",
        		"ADDITIONAL_INFO":       "Additional information",
        		"UTM_SOURCE":            "google",
        		"UTM_MEDIUM":            "CPC",
        		"PARENT_ID_1220":        22,
        		"UF_CRM_1721244482250":  "Hello World!",
        	},
        	"params": b24.Params{
        		"REGISTER_SONET_EVENT": "N",
        	},
        })
        if err != nil {
        	return fmt.Errorf("crm.deal.add: %w", err)
        }
        
        var newID b24.ID
        if err := json.Unmarshal(res.Result, &newID); err != nil {
        	return fmt.Errorf("parse response: %w", err)
        }
        fmt.Println("id:", newID)
        

Response Handling

HTTP Status: 200

{
            "result": 394,
            "time": {
                "start": 1725013197.635808,
                "finish": 1725013198.580873,
                "duration": 0.9450650215148926,
                "processing": 0.6822988986968994,
                "date_start": "2024-08-30T12:19:57+02:00",
                "date_finish": "2024-08-30T12:19:58+02:00",
                "operating": 0
            }
        }
        

Returned Data

Name
type

Description

result
integer

Root element of the response, contains the identifier of the created deal

time
time

Information about the execution time of the request

Error Handling

HTTP Status: 400

{
            "error": "",
            "error_description": "Parameter 'fields' must be array."
        }
        

Name
type

Description

error
string

String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only error_description shows the reason

error_description
string

Error message for the developer. Do not show it to the end user without processing

Possible Error Codes

Code

Description

Value

Empty value

Parameter 'fields' must be array

The parameter fields is not an object

Empty value

Parameter 'params' must be array

The parameter params is not an object

Empty value

Access denied

The user does not have permission to "add" deals

Empty value

Disk resource exhausted

Empty value

Invalid value for the "Currency" field

Statuses and System Error Codes

HTTP Status: 4xx, 5xx

The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.

Status

Code
Error Message

Description

500

INTERNAL_SERVER_ERROR
Internal server error

An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support

503

QUERY_LIMIT_EXCEEDED
Too many requests

The request intensity limit has been exceeded

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit

401

NO_AUTH_FOUND
Wrong authorization data

The request contains no authorization data: neither an access token nor a webhook code was passed

401

INVALID_REQUEST
Https required

Methods are called over the HTTPS protocol only

401

OVERLOAD_LIMIT
REST API is blocked due to overload

The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support

401

ACCESS_DENIED
REST is available only on commercial plans

REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

No active webhook with the specified user identifier and secret code was found

404

ERROR_METHOD_NOT_FOUND
Method not found!

No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with provided by the access token

401

expired_token
The access token provided has expired

The access token has expired

401

user_access_error
The user does not have access to the application

The application is installed, but the Bitrix24 administrator has granted access to it only to specific users

403

PORTAL_DELETED
Portal was deleted

The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning