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

Get contact

GET /v1/contacts/:id

Returns a contact by ID with all fields.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionContact ID. List: GET /v1/contacts
Parameterinclude (query) Typestring Requiredno DescriptionComma-separated related data: company, companyBinding. The result is in data._included. See Related data
Parameterselect (query) Typestring Requiredno DescriptionComma-separated response fields, for example id,name,lastName. Without it, every field is returned. The id field is always returned. Names come from Contact fields

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/contacts/71" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/contacts/71" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/71', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/contacts/71', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

For more on include, see Related data.

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typeobject DescriptionThe contact with all fields, including user fields ufCrm_*. With the select parameter, only the listed fields and id are returned. All fields — Contact fields
Fielddata._included Typeobject DescriptionRelated data. Returned only with the include parameter: company is the contact's primary company or null; companyBindings is an array of all linked companies with the binding fields isPrimary, sort and roleId. See Related data
Fieldmeta.warnings Typearray DescriptionReturned when a name that is absent from the contact schema is listed alongside * in select: the contact comes back without that field. Each warning is an object with code, field and message, and the code is UNKNOWN_SELECT_FIELD. Without *, such a name causes the whole request to be rejected

(include)

To retrieve related entities along with the contact, use the include parameter in the GET request:

GET /v1/contacts/71?include=company

Available include values: company, companyBinding. The result is in data._included.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 71,
    "name": "John",
    "lastName": "Brown",
    "companyId": 1,
    "assignedById": 1,
    "sourceId": "WEB",
    "typeId": "CLIENT",
    "phone": "+12025550123",
    "phoneWork": "+12025550123",
    "email": "info@example.com",
    "emailWork": "info@example.com",
    "emailHome": "home@example.com",
    "hasPhone": true,
    "hasEmail": true,
    "fm": [
      { "id": 41, "typeId": "PHONE", "valueType": "WORK", "value": "+12025550123" },
      { "id": 43, "typeId": "EMAIL", "valueType": "WORK", "value": "info@example.com" },
      { "id": 45, "typeId": "EMAIL", "valueType": "HOME", "value": "home@example.com" }
    ],
    "createdTime": "2020-05-08T10:48:20+00:00",
    "updatedTime": "2025-08-22T13:01:31+00:00"
  }
}

The phone number and email address in the response are strings containing the primary value. Values by type are in phoneWork, phoneMobile, emailWork, and emailHome. The complete list with types is in the fm[] array ({ id, typeId, valueType, value }, where id identifies the entry). Check hasPhone/hasEmail to determine whether a value exists: if there is no phone number, phone is an empty string. The API cannot update or delete an individual fm[] entry by its id — PATCH adds new entries.

Error response example

404 — contact not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionContact not found
HTTP400 CodeUNKNOWN_SELECT_FIELD Descriptionselect contains an unknown field. The message lists the allowed names
HTTP403 CodeACCESS_DENIED DescriptionNo access to the contact
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

For the full list of common API errors, see Errors.

See also