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

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

Contacts

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

Bitrix24 API: crm.item.* Scope: crm

Create contact

POST /v1/contacts

Creates a new contact in CRM.

Request fields (body)

Parameter Type Description
Parametername Typestring DescriptionFirst name, at most 50 Unicode code points. Longer values are rejected before writing; the name is not truncated.
ParameterlastName Typestring DescriptionLast name
ParametersecondName Typestring DescriptionMiddle name
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" }]
ParametercompanyId Typenumber DescriptionCompany ID. Lookup: GET /v1/companies
Parameterpost Typestring DescriptionPosition
Parametercomments Typestring DescriptionComment
ParametertypeId Typestring DescriptionContact type. List: GET /v1/statuses?filter[entityId]=CONTACT_TYPE
ParametersourceId Typestring DescriptionSource. List: GET /v1/statuses?filter[entityId]=SOURCE
ParametersourceDescription Typestring DescriptionSource description
ParameterassignedById Typenumber DescriptionAssigned user. List: GET /v1/users
Parameteropened Typeboolean DescriptionAvailable to everyone
ParameterleadId Typenumber DescriptionID of the lead the contact 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/contacts/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/contacts/fields.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/contacts \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John",
    "lastName": "Brown",
    "phone": "+12025550123",
    "email": "john@example.com",
    "companyId": 15,
    "post": "Manager",
    "typeId": "CLIENT"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/contacts \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John",
    "lastName": "Brown",
    "phone": "+12025550124",
    "email": "john@example.com",
    "companyId": 15,
    "post": "Manager",
    "typeId": "CLIENT"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'John',
    lastName: 'Brown',
    phone: '+12025550125',
    email: 'john@example.com',
    companyId: 15,
    post: 'Manager',
    typeId: 'CLIENT',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'John',
    lastName: 'Brown',
    phone: '+12025550126',
    email: 'john@example.com',
    companyId: 15,
    post: 'Manager',
    typeId: 'CLIENT',
  }),
})

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

Alternative form — array of objects with explicit `typeId`

If you need to specify multiple values or an explicit type (HOME, MOBILE):

JSON 
{
  "phone": [
    { "value": "+12025550127", "typeId": "WORK" },
    { "value": "+12025550123", "typeId": "MOBILE" }
  ],
  "email": [
    { "value": "work@example.com", "typeId": "WORK" },
    { "value": "personal@example.com", "typeId": "HOME" }
  ]
}

Response fields

Field Type Description
Fieldid Typenumber DescriptionID of the created contact
Fieldname Typestring DescriptionFirst name, at most 50 Unicode code points. Longer values are rejected before writing; the name is not truncated.
FieldlastName Typestring DescriptionLast name
FieldcompanyId Typenumber DescriptionCompany ID
FieldassignedById Typenumber DescriptionAssigned user
FieldcreatedBy Typenumber DescriptionCreator
FieldcreatedTime Typedatetime DescriptionCreation date
FieldupdatedTime Typedatetime DescriptionModification date
FieldtypeId Typestring DescriptionContact type
FieldsourceId Typestring DescriptionSource

The response contains all contact fields, including user fields (ufCrm*).

The contact card URL in Bitrix24 is built from id:

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

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

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 2457,
    "name": "John",
    "lastName": "Brown",
    "secondName": null,
    "companyId": 15,
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T12:26:17+00:00",
    "updatedTime": "2026-04-15T12:26:17+00:00",
    "opened": true,
    "typeId": "CLIENT",
    "sourceId": "CALL",
    "post": "Manager"
  }
}

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
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens
HTTP400 CodeINVALID_REQUEST DescriptionInvalid fields
HTTP400 CodeREADONLY_FIELD DescriptionThe request body contains a read-only field, such as shortName. Such fields are marked in the RO column of Contact fields
HTTP400 CodeMULTIFIELD_ID_NOT_SUPPORTED Descriptionphone, email 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

Full list of common API errors — Errors.

See also