#Create contact

POST /v1/contacts

Creates a new contact in CRM.

#Request fields (body)

Parameter Type Description
name string First name
lastName string Last name
secondName string Middle name
phone string | string[] | object[] Phone. Accepts three forms: a string "+7...", an array of strings ["+7...", "+7..."], or an array of objects [{ "value": "+7...", "typeId": "WORK" }, …]. typeId: WORK | HOME | MOBILE | OTHER (default WORK). ⚠ The B24-native UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
email string | string[] | object[] Email. 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). ⚠ The B24-native UPPER form [{ "VALUE": "...", "VALUE_TYPE": "WORK" }] is not accepted — it returns 400 INVALID_MULTIFIELD_SHAPE. Use camelCase: [{ "value": "...", "typeId": "WORK" }]
companyId number Company ID. Lookup: GET /v1/companies
post string Position
comments string Comment
typeId string Contact type. List: GET /v1/statuses?filter[entityId]=CONTACT_TYPE
sourceId string Source. List: GET /v1/statuses?filter[entityId]=SOURCE
sourceDescription string Source description
assignedById number Assigned user. List: GET /v1/users
opened boolean Available to everyone
leadId number ID of the lead the contact was created from

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

#Examples

#curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/contacts \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ivan",
    "lastName": "Petrov",
    "phone": "+79161234567",
    "email": "ivan@company.ru",
    "companyId": 15,
    "post": "Manager",
    "typeId": "CLIENT"
  }'

#curl — OAuth app

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/contacts \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ivan",
    "lastName": "Petrov",
    "phone": "+79161234567",
    "email": "ivan@company.ru",
    "companyId": 15,
    "post": "Manager",
    "typeId": "CLIENT"
  }'

#JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/contacts', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Ivan',
    lastName: 'Petrov',
    phone: '+79161234567',
    email: 'ivan@company.ru',
    companyId: 15,
    post: 'Manager',
    typeId: 'CLIENT',
  }),
})

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

#JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/contacts', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Ivan',
    lastName: 'Petrov',
    phone: '+79161234567',
    email: 'ivan@company.ru',
    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": "+79161234567", "typeId": "WORK" },
    { "value": "+79161112233", "typeId": "MOBILE" }
  ],
  "email": [
    { "value": "work@company.ru", "typeId": "WORK" },
    { "value": "personal@me.ru", "typeId": "HOME" }
  ]
}

#Response fields

Field Type Description
id number ID of the created contact
name string First name
lastName string Last name
companyId number Company ID
assignedById number Assigned user
createdBy number Creator
createdTime datetime Creation date
updatedTime datetime Modification date
typeId string Contact type
sourceId string Source

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

The contact card URL in Bitrix24 is built from id:

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

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

#Response example

JSON 
{
  "success": true,
  "data": {
    "id": 2457,
    "name": "Ivan",
    "lastName": "Petrov",
    "secondName": null,
    "companyId": 15,
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T12:26:17+03:00",
    "updatedTime": "2026-04-15T12:26:17+03: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
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