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

Create company

POST /v1/companies

Creates a new company in CRM.

Request fields (body)

Parameter Type Description
Parametertitle Typestring DescriptionCompany name
ParametertypeId Typestring DescriptionCompany type: CUSTOMER, SUPPLIER, COMPETITOR. List of values: GET /v1/statuses?filter[entityId]=COMPANY_TYPE
Parameterindustry Typestring DescriptionIndustry: IT, TELECOM, MANUFACTURING, etc. List: GET /v1/statuses?filter[entityId]=INDUSTRY
Parameterrevenue Typenumber DescriptionAnnual revenue
ParametercurrencyId Typestring DescriptionRevenue currency. List: GET /v1/currencies
Parameterphone Typestring | string[] | object[] DescriptionPhone. Accepts three forms: a string "+1...", an array of strings ["+1...", "+1..."], or an array of objects [{ "value": "+1...", "typeId": "WORK" }, …]. typeId: WORK | HOME | MOBILE | OTHER (default WORK). Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
Parameteremail Typestring | string[] | object[] DescriptionEmail. Accepts three forms: a string "a@b.com", an array of strings ["a@b.com", "b@c.com"], or an array of objects [{ "value": "a@b.com", "typeId": "WORK" }, …]. typeId: WORK | HOME | MAILING | OTHER (default WORK). Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
Parameterweb Typestring | string[] | object[] DescriptionWebsite. Accepts three forms: a string "https://acme.com", an array of strings, or an array of objects [{ "value": "https://...", "typeId": "WORK" }]. typeId: WORK | HOME | OTHER (default WORK). Important: the UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
Parametercomments Typestring DescriptionComment
ParametersourceId Typestring DescriptionSource. List: GET /v1/statuses?filter[entityId]=SOURCE
ParametersourceDescription Typestring DescriptionSource description
ParameterassignedById Typenumber DescriptionResponsible person. List: GET /v1/users
Parameteropened Typeboolean DescriptionAvailable to everyone
ParameterleadId Typenumber DescriptionID of the lead the company was created from
ParameterufCrm* Typeper field schema DescriptionA user field of the Bitrix24 account, for example ufCrmProjectCode. The actual name and type are in the schema GET /v1/companies/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/companies/fields.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/companies \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme LLC",
    "typeId": "CUSTOMER",
    "industry": "IT",
    "phone": "+12025550123",
    "email": "info@example.com",
    "web": "https://example.com"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/companies \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme LLC",
    "typeId": "CUSTOMER",
    "industry": "IT",
    "phone": "+12025550124",
    "email": "info@example.com",
    "web": "https://example.com"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/companies', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Acme LLC',
    typeId: 'CUSTOMER',
    industry: 'IT',
    phone: '+12025550125',
    email: 'info@example.com',
    web: 'https://example.com',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/companies', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Acme LLC',
    typeId: 'CUSTOMER',
    industry: 'IT',
    phone: '+12025550126',
    email: 'info@example.com',
    web: 'https://example.com',
  }),
})

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

Alternative form — array of objects with explicit `typeId`

If you need to specify several values or an explicit type (HOME, OTHER):

JSON 
{
  "phone": [
    { "value": "+12025550127", "typeId": "WORK" },
    { "value": "+12025550123", "typeId": "OTHER" }
  ],
  "email": [
    { "value": "info@example.com", "typeId": "WORK" },
    { "value": "sales@example.com", "typeId": "MAILING" }
  ],
  "web": [
    { "value": "https://example.com", "typeId": "WORK" },
    { "value": "https://shop.example.com", "typeId": "OTHER" }
  ]
}

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typeobject DescriptionThe created company with all fields, including user fields ufCrm*. All fields — Company fields
Fielddata.id Typenumber DescriptionID of the created company
Fielddata.title Typestring DescriptionName
Fielddata.typeId Typestring DescriptionCompany type
Fielddata.industry Typestring DescriptionIndustry
Fielddata.assignedById Typenumber DescriptionID of the responsible person
Fielddata.createdBy Typenumber DescriptionID of the creator
Fielddata.createdTime Typedatetime DescriptionCreation date
Fielddata.updatedTime Typedatetime DescriptionModification date

The company card URL in Bitrix24 is built from id:

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

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

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 2923,
    "title": "Acme LLC",
    "typeId": "CUSTOMER",
    "industry": "IT",
    "revenue": 0,
    "currencyId": "USD",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T12:53:59+00:00",
    "updatedTime": "2026-04-15T12:53:59+00:00",
    "opened": true
  }
}

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 DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP400 CodeINVALID_REQUEST DescriptionInvalid fields
HTTP400 CodeINVALID_MULTIFIELD_SHAPE DescriptionWrong shape for phone, email or web: the form with upper-case VALUE / VALUE_TYPE keys is not accepted; the expected shape is [{ "value", "typeId" }]. The same code is returned when phone, email or web holds an object without value — for example empty or with keys such as n0, 0 or 011 — or a number or true/false, on its own or as an array item, or when the raw fm is not an array, for example a string, a number, an empty object or an object keyed by type such as PHONE: fm is accepted only as an array [{ "typeId", "valueType", "value" }]. The request is refused and nothing is written
HTTP400 CodeMULTIFIELD_ID_NOT_SUPPORTED Descriptionphone, email, web or the raw fm[] contains an object with an id field. There is nothing to address on create: Bitrix24 assigns multifield row IDs itself, so the request is refused and nothing is written. The same refusal applies when fm, phone, email or web is sent as an object keyed by row IDs ({"fm": {"11": {…}}})

Full list of common API errors — Errors.

See also