Get Contact by Id crm.contact.get

Scope: crm

Who can execute the method: any user with "read" access permission for contacts

Method Development Stopped

The method crm.contact.get continues to function, but there is a more relevant alternative crm.item.get.

The method crm.contact.get returns a contact by its identifier.

To get a list of companies associated with the contact, use the method crm.contact.company.items.get.

Method Parameters

Required parameters are marked with *

Name `type`	Description
id* `integer`	Identifier of the contact. Can be obtained using the methods `crm.contact.list` or `crm.contact.add`

Code Examples

How to Use Examples in Documentation

Get contact with id = 23

cURL (Webhook)

cURL (OAuth)

PHP

BX24.js

PHP CRest

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"ID":23}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.contact.get

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"ID":23,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.contact.get

try
        {
        	const response = await $b24.callMethod(
        		'crm.contact.get',
        		{
        			id: 23,
        		}
        	);
        	
        	const result = response.getData().result;
        	result.error()
        		? console.error(result.error())
        		: console.info(result)
        	;
        }
        catch( error )
        {
        	console.error('Error:', error);
        }

try {
            $contactId = 123; // Example contact ID
            $contactResult = $serviceBuilder
                ->getCRMScope()
                ->contact()
                ->get($contactId);
            $itemResult = $contactResult->contact();
            print("ID: " . $itemResult->ID . PHP_EOL);
            print("Name: " . $itemResult->NAME . PHP_EOL);
            print("Last Name: " . $itemResult->LAST_NAME . PHP_EOL);
            print("Birthday: " . $itemResult->BIRTHDATE?->format(DATE_ATOM) . PHP_EOL);
            print("Created Date: " . $itemResult->DATE_CREATE->format(DATE_ATOM) . PHP_EOL);
            print("Modified Date: " . $itemResult->DATE_MODIFY->format(DATE_ATOM) . PHP_EOL);
        } catch (Throwable $e) {
            print("Error: " . $e->getMessage() . PHP_EOL);
        }

BX24.callMethod(
            'crm.contact.get',
            {
                id: 23,
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data())
                ;
            },
        );

require_once('crest.php');
        
        $result = CRest::call(
            'crm.contact.get',
            [
                'ID' => 23
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Response Handling

HTTP status: 200

{
            "result": {
                "ID": "43",
                "POST": "Administrator",
                "COMMENTS": "\nExample comment inside the contact\n\n[B]Bold text[\/B]\n[I]Italic[\/I]\n[U]Underlined[\/U]\n[S]Strikethrough[\/S]\n[B][I][U][S]Mix[\/S][\/U][\/I][\/B]\n\n[LIST]\n[*]List item #1\n[*]List item #2\n[*]List item #3\n[\/LIST]\n\n[LIST=1]\n[*]Numbered list item #1\n[*]Numbered list item #2\n[*]Numbered list item #3\n[\/LIST]\n",
                "HONORIFIC": "HNR_EN_1",
                "NAME": "John",
                "SECOND_NAME": "Doe",
                "LAST_NAME": "Smith",
                "PHOTO": null,
                "LEAD_ID": null,
                "TYPE_ID": "PARTNER",
                "SOURCE_ID": "WEB",
                "SOURCE_DESCRIPTION": "*Additional information about the source*",
                "COMPANY_ID": "12",
                "BIRTHDATE": "2001-11-11T02:00:00+02:00",
                "EXPORT": "N",
                "HAS_PHONE": "Y",
                "HAS_EMAIL": "Y",
                "HAS_IMOL": "N",
                "DATE_CREATE": "2024-08-15T10:38:21+02:00",
                "DATE_MODIFY": "2024-08-15T10:38:21+02:00",
                "ASSIGNED_BY_ID": "6",
                "CREATED_BY_ID": "1",
                "MODIFY_BY_ID": "1",
                "OPENED": "Y",
                "ORIGINATOR_ID": null,
                "ORIGIN_ID": null,
                "ORIGIN_VERSION": null,
                "FACE_ID": null,
                "LAST_ACTIVITY_TIME": "2024-08-15T10:38:21+02:00",
                "ADDRESS": null,
                "ADDRESS_2": null,
                "ADDRESS_CITY": null,
                "ADDRESS_POSTAL_CODE": null,
                "ADDRESS_REGION": null,
                "ADDRESS_PROVINCE": null,
                "ADDRESS_COUNTRY": null,
                "ADDRESS_LOC_ADDR_ID": null,
                "UTM_SOURCE": "google",
                "UTM_MEDIUM": "CPC",
                "UTM_CAMPAIGN": "summer_sale",
                "UTM_CONTENT": "header_banner",
                "UTM_TERM": "discount",
                "PARENT_ID_1224": "12",
                "LAST_ACTIVITY_BY": "1",
                "UF_CRM_1720697698689": "Example value of a custom field with type \u0022String\u0022",
                "PHONE": [
                {
                    "ID": "156",
                    "VALUE_TYPE": "WORK",
                    "VALUE": "+13333333555",
                    "TYPE_ID": "PHONE"
                },
                {
                    "ID": "157",
                    "VALUE_TYPE": "HOME",
                    "VALUE": "+15599888666",
                    "TYPE_ID": "PHONE"
                }
                ],
                "EMAIL": [
                {
                    "ID": "158",
                    "VALUE_TYPE": "MAILING",
                    "VALUE": "johnsmith@example.mailing",
                    "TYPE_ID": "EMAIL"
                },
                {
                    "ID": "159",
                    "VALUE_TYPE": "WORK",
                    "VALUE": "johnsmith@example.work",
                    "TYPE_ID": "EMAIL"
                }
                ]
            },
            "time": {
                "start": 1723736139.883652,
                "finish": 1723736140.299369,
                "duration": 0.41571712493896484,
                "processing": 0.14158892631530762,
                "date_start": "2024-08-15T17:35:39+02:00",
                "date_finish": "2024-08-15T17:35:40+02:00"
            }
        }

Returned Data

Name `type`	Description
result `contact`	Root element of the response. Contains information about the contact fields. The structure is described below
time `time`	Object containing information about the request execution time

contact

Name `type`	Description
ID `integer`	Identifier of the contact
POST `string`	Position
COMMENTS `text`	Comment
HONORIFIC `crm_status`	Salutation
NAME `string`	First name
SECOND_NAME `string`	Middle name
LAST_NAME `string`	Last name
PHOTO `file`	Photo
LEAD_ID `crm_lead`	Identifier of the lead based on which the contact was created
TYPE_ID `crm_status`	Type of contact
SOURCE_ID `crm_status`	Source
SOURCE_DESCRIPTION `text`	Additional information about the source
COMPANY_ID `crm_company`	Identifier of the main company
BIRTHDATE `date`	Date of birth
EXPORT `boolean`	Whether the contact is included in the export. Possible values: `Y` — yes `N` — no
HAS_PHONE `boolean`	Whether a phone is set. Possible values: `Y` — yes `N` — no
HAS_EMAIL `boolean`	Whether an e-mail is set. Possible values: `Y` — yes `N` — no
HAS_IMOL `boolean`	Whether an open channel is set. Possible values: `Y` — yes `N` — no
DATE_CREATE `datetime`	Creation date
DATE_MODIFY `datetime`	Modification date
ASSIGNED_BY_ID `user`	Responsible person
CREATED_BY_ID `user`	Created by
MODIFY_BY_ID `user`	Modified by
OPENED `boolean`	Available to everyone. Possible values: `Y` — yes `N` — no
FACE_ID `integer`	Link to faces from the `faceid` module
LAST_ACTIVITY_TIME `datetime`	Last activity
LAST_ACTIVITY_BY `user`	Who performed the last activity in the timeline
UTM_SOURCE `string`	Advertising system (Google Ads, Facebook Ads, etc.)
UTM_MEDIUM `string`	Type of traffic. Possible values: `CPC` — ads `CPM` — banners
UTM_CAMPAIGN `string`	Designation of the advertising campaign
UTM_CONTENT `string`	Content of the campaign. For example, for contextual ads
UTM_TERM `string`	Search condition of the campaign. For example, keywords for contextual advertising
PHONE `crm_multifield[]`	Phone
EMAIL `crm_multifield[]`	E-mail
WEB `crm_multifield[]`	Website
IM `crm_multifield[]`	Messenger
LINK `crm_multifield[]`	Links. Service field

Fields for external data source connections

If the contact was created by an external system, then:

the field ORIGINATOR_ID stores the string identifier of that system
the field ORIGIN_ID stores the string identifier of the contact in that external system
the field ORIGIN_VERSION stores the version of the contact data in that external system

Name `type`	Description
ORIGINATOR_ID `string`	External source
ORIGIN_ID `string`	Identifier of the element in the external source
ORIGIN_VERSION `string`	Version of the original

Deprecated Fields

Address fields in the contact are deprecated and are only used for compatibility mode. To work with the address, use details.

Name `type`	Description
ADDRESS `string`	Address
ADDRESS_2 `string`	Second line of the address
ADDRESS_CITY `string`	City
ADDRESS_POSTAL_CODE `string`	Postal code
ADDRESS_REGION `string`	Region
ADDRESS_PROVINCE `string`	Province
ADDRESS_COUNTRY `string`	Country
ADDRESS_LOC_ADDR_ID `integer`	Identifier of the location address

Fields of type crm_multifield

Fields of type crm_multifield (PHONE, EMAIL, WEB, IM, LINK) are explicitly returned by this method only if the values of this field are not equal to null.

Error Handling

HTTP status: 400

{
            "error": "",
            "error_description": "ID is not defined or invalid."
        }

Name `type`	Description
error `string`	String error code. It may consist of digits, Latin letters, and underscores
error_description `error_description`	Textual description of the error. The description is not intended to be shown to the end user in its raw form

Possible Error Codes

Description	Value
`ID is not defined or invalid`	The `id` parameter is not provided or the provided value is not a positive integer
`Access denied`	The user does not have permission to "Read" the contact
`Not found`	The contact with the provided `id` was not found

Statuses and System Error Codes

HTTP Status: 20x, 40x, 50x

The errors described below may occur when calling any method.

Status	Code Error Message	Description
`500`	`INTERNAL_SERVER_ERROR` Internal server error	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`500`	`ERROR_UNEXPECTED_ANSWER` Server returned an unexpected response	An internal server error has occurred, please contact the server administrator or Bitrix24 technical support
`503`	`QUERY_LIMIT_EXCEEDED` Too many requests	The request intensity limit has been exceeded
`405`	`ERROR_BATCH_METHOD_NOT_ALLOWED` Method is not allowed for batch usage	The current method is not allowed to be called using batch
`400`	`ERROR_BATCH_LENGTH_EXCEEDED` Max batch length exceeded	The maximum length of parameters passed to the batch method has been exceeded
`401`	`NO_AUTH_FOUND` Wrong authorization data	Invalid access token or webhook code
`400`	`INVALID_REQUEST` Https required	The methods must be called using the HTTPS protocol
`503`	`OVERLOAD_LIMIT` REST API is blocked due to overload	The REST API is blocked due to overload. This is a manual individual block, to remove it you need to contact Bitrix24 technical support
`403`	`ACCESS_DENIED` REST API is available only on commercial plans	The REST API is available only on commercial plans
`403`	`INVALID_CREDENTIALS` Invalid request credentials	The user whose access token or webhook was used to call the method lacks permissions
`404`	`ERROR_MANIFEST_IS_NOT_AVAILABLE` Manifest is not available	The manifest is not available
`403`	`insufficient_scope` The request requires higher privileges than provided by the webhook token	The request requires higher privileges than those provided by the webhook token
`401`	`expired_token` The access token provided has expired	The provided access token has expired
`403`	`user_access_error` The user does not have access to the application	The user does not have access to the application. This means that the application is installed, but the account administrator has allowed access to this application only for specific users
`500`	`PORTAL_DELETED` Portal was deleted	The public part of the site is closed. To open the public part of the site on an on-premise installation, disable the option "Temporary closure of the public part of the site". Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site

Continue Learning

Update contact

Get list of contacts

Get Contact by Id crm.contact.get

Method ParametersMethod Parameters

Code ExamplesCode Examples

Response HandlingResponse Handling

Returned DataReturned Data

contactcontact

Error HandlingError Handling

Possible Error CodesPossible Error Codes

Statuses and System Error CodesStatuses and System Error Codes

Continue LearningContinue Learning