Контакты и компании

Получение контакта или компании

Метод позволяет получить контакт или компанию по уникальному идентификатору

URL метода

GET /api/v4/{contacts|companies}/{id}

Параметры GET

Параметр Тип Описание
id int Уникальный идентификатор контакта или компании

Пример запроса для получения контакта:


GET http://example.amocrm.ru/api/v4/contacts/403181

Пример ответа:


{
    "id": 403181,
    "name": "Иван Иванов",
    "first_name": “Иван”,
    "last_name": “Иванов”,
    "responsible_user_id": 112313,
    "group_id": 3625,
    "company_id": 40318188,
    "created_by": 939733,
    "updated_by": 939743,
    "created_at": 1465396143,
    "updated_at": 1465396294,
    "closest_task_at": null,
    "custom_fields_values": [
        {
            "field_id": 1277732,
            "field_name": "Дополнительное значение для примера",
            "field_code": null,
            "field_type": "numeric",
            "values": [
                {
                    "value": "415949"
                }
            ]
        }
    ],
    "account_id": 1234114,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts/403181"
        }
    },
    "_embedded": {
        "tags": [],
        "companies": [
            {
                "id": 40318188,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/companies/40318188"
                    }
                }
            }
        ]
    }
}

Возможные параметры для контакта или компании описаны ниже:

Параметр Контакт Компания Описание
id + + Уникальный идентификатор сущности
name + + Имя контакта или компании
first_name + Личное имя
last_name + Фамилия
company_id + ID компании, привязанной к контакту
responsible_user_id + + ID ответственного за создание контакта/компании
created_by + + Кем была создана компания/контакт
created_at + + Когда была создана компания/контакт
updated_by + + Кем была обновлена компания/контакт
updated_at + + Когда была обновлена компания/контакт
closest_task_at + + Время ближайшей задачи по компании/контакту
custom_fields_values + + Массив, содержащий информацию по дополнительным полям
_embedded/tags + + Массив содержащий теги связанные с контактом/компанией
_embedded/companies + Массив содержащий все компании связанные с этим контактом

Получение списка контактов или компании

Метод позволяет получить список всех контактов или компаний с возможностью фильтрации и постраничной выборки.

URL метода

GET /api/v4/{entity_type}

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности: contacts, companies

Возможные query параметры запроса:

Параметр Описание
page Страница выборки
limit Кол-во выбираемых строк (системное ограничение 500)
offset Сдвиг выборки (с какой строки выбирать). Работает, только при условии, что limit тоже указан
query Поисковый запрос (Осуществляет поиск по заполненным полям сущности)
responsible_user_id Дополнительный фильтр поиска, по ответственному пользователю (Можно передавать в виде массива)
filter[date_create] Выбрать сущности по дате создания (нужно передавать массив с параметрами from, to)
filter[date_modify] Выбрать сущности по дате изменения (нужно передавать массив с параметрами from, to)
filter[task] Выбрать сущности без задач – 1
Выбрать сущности с невыполненными задачами – 2

Пример запроса:

В данном примере мы получим все контакты, которые были созданы в период между 5 и 6 мая 2020 года.


GET https://test.amocrm.ru/api/v4/contacts?filter[date_create][from]=1588636800&filter[date_create][to]=1588666032

Пример ответа:


{
    "_page": 1,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts?filter%5Bdate_create%5D%5Bfrom%5D=1588636800&filter%5Bdate_create%5D%5Bto%5D=1588666032&page=1&limit=50&offset=0"
        },
        "next": {
            "href": "https://example.amocrm.ru/api/v4/contacts?filter%5Bdate_create%5D%5Bfrom%5D=1588636800&filter%5Bdate_create%5D%5Bto%5D=1588666032&page=2&limit=50&offset=0"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 40401633,
                "name": "Иван Иванов”,
                "first_name": "Иван",
                "last_name": "Иванов",
                "responsible_user_id": 123123123,
                "group_id": 836,
                "company_id": null,
                "created_by": 346011,
                "updated_by": 346011,
                "created_at": 1588665991,
                "updated_at": 1588666231,
                "closest_task_at": null,
                "custom_fields_values": null,
                "account_id": 142141,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/40401633"
                    }
                },
                "_embedded": {
                    "tags": [],
                    "companies": []
                }
            }
        ]
    }
}

Создание контактов или компаний

Метод позволяет создавать компании или контакты по одной или пакетно.

URL метода

POST /api/v4/{entity_type}

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности: contacts, companies

Для создания контактов или компаний необходимо передать массив с JSON-объектами, которые содержат параметры контакта/компании, описанные здесь

Пример создания контакта:


POST https://example.amocrm.ru/api/v4/contacts
Content-Type: application/json

[
    {
        "first_name": "Ivan",
        "last_name": "Ivanov",
        "custom_fields_values": [
            {
                "field_id": 271316,
                "field_name": "Должность",
                "values": [
                    {
                        "value": "Директор"
                    }
                ]
            }
        ]
    },
    {
        "name": "Владимир Смирнов",
        “created_by”: 47272
    }
]

Пример ответа:


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 40401635,
                "request_id": 0,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/40401635"
                    }
                },
                {
                  "id": 40401636,
                  "request_id": 0,
                   "_links": {
                       "self": {
                           "href": "https://example.amocrm.ru/api/v4/contacts/40401636"
                   }
                }
            }
        ]
    }
}

Редактирование контактов или компаний

Метод позволяет редактировать компании или контакты по одной или пакетно.

URL метода:

PATCH /api/v4/{entity_type}/{id} – для редактирования сущности по идентификатору

PATCH /api/v4/{entity_type} – для редактирования пакетно

Параметры GET

Параметр Тип Описание
entity_type string Тип сущности: contacts, companies
id int Уникальный идентификатор контакта или компании

Для изменения контакта или компании по ее идентификатору необходимо отправить тело запроса с JSON-объектом, содержащий параметры из списка здесь, например:


PATCH https://example.amocrm.ru/api/v4/contacts/40401633
Content-Type: application/json

{
   "first_name": "Иван",
   “last_name”: “Иванов”,
   "custom_fields_values": [
        {
            "field_id": 66192,
            "field_name": "Телефон",
            "values": [
                {
                    "value": "79999999999",
                    "enum_id": 193226
                }
            ]
        }
   ]
}

Пример ответа:


{
   "id": 40401635,
   "name": "Иван Иванов",
   "first_name": "Иван",
   “last_name”: “Иванов”,
    "updated_at": 1588672104,
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts/40401633"
        }
    }
}

Для изменения контактов или компаний пакетно необходимо указать массив из json, содержащий в себе обязательное поле id (идентификатор контакта/компании) и дополнительные параметры из списка здесь, например:


PATCH https://example.amocrm.ru/api/v4/contacts
Content-Type: application/json

[
    {
        "id": 40401635,
        "first_name": "Владимир",
        "last_name": "Смирнов",
        "custom_fields_values": [
            {
                "field_id": 271316,
                "field_name": "Должность",
                "values": [
                    {
                        "value": "Директор"
                    }
                ]
            }
        ]
    },
    {
        "id": 40401633,
        "first_name": "Виталий",
        "last_name": "Попов"
    }
]

Пример ответа:


{
    "_links": {
        "self": {
            "href": "https://example.amocrm.ru/api/v4/contacts"
        }
    },
    "_embedded": {
        "contacts": [
            {
                "id": 40401635,
                "name": "Владимир Смирнов",
                "first_name": "Владимир",
                "last_name": "Смирнов",
                "updated_at": 1588671279,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/40401635"
                    }
                }
            },
            {
                "id": 40401636,
                "name": "Виталий Попов",
                "first_name": "Виталий",
                "last_name": "Попов",
                "updated_at": 1588671279,
                "_links": {
                    "self": {
                        "href": "https://example.amocrm.ru/api/v4/contacts/40401636"
                    }
                }
            }
        ]
    }
}

Смотрите также

КОДЫ ОШИБОК API