Возвращает компании, соответствующие условиям, с указанием их роли в группе.

Параметры

Порядок поиска

• Если передан id или name, поиск выполняется по ним. При поиске по name на одной странице обрабатывается 50 результатов amoCRM.
• В остальных случаях выборка строится по responsible_user_id, lead_id, contact_id — 25 записей на страницу.
• Результат дополнительно фильтруется по всем переданным responsible_user_id, lead_id, contact_id.

Пример

GET /companies/search?name=ООО&responsible_user_id=2320770

{
  "status": true,
  "response": {
    "items": [
      {
        "id": 29875257,
        "name": "ООО «Ромашка»",
        "responsible_user_id": 2320770,
        "created_at": 1701094831,
        "role": "linked",
        "main_id": 17493287
      },
      {
        "id": 29875277,
        "name": "ООО «Лютик»",
        "responsible_user_id": 2320770,
        "created_at": 1701094861,
        "role": "none",
        "main_id": null
      }
    ],
    "page": 1,
    "has_more": false
  }
}

Поля ответа

• role — роль компании в группе: main, linked или none.
• main_id — идентификатор главной компании группы.
• created_at — дата создания в формате Unix time.

Возвращает группу, в которую входит указанная компания.

Параметры

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

{
  "status": true,
  "response": {
    "main_id": 17493287,
    "linked": [4926915, 29875257]
  }
}

Возвращает данные компании: поля, теги, связанные сделки и контакты, роль в группе.

Параметры

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

{
  "status": true,
  "response": {
    "id": 29875257,
    "name": "ООО «Ромашка»",
    "responsible_user_id": 2320770,
    "created_at": 1701094831,
    "updated_at": 1729500000,
    "tags": ["api"],
    "custom_fields": [
      {
        "field_id": 101,
        "field_code": "PHONE",
        "field_name": "Телефон",
        "field_type": "multitext",
        "values": [
          {
            "value": "+70000000000",
            "enum_id": 1,
            "enum_code": "WORK"
          }
        ]
      },
      {
        "field_id": 205,
        "field_code": null,
        "field_name": "ИНН",
        "field_type": "text",
        "values": [{"value": "7700000000"}]
      }
    ],
    "leads": [123456, 123457],
    "leads_has_more": false,
    "contacts": [555],
    "contacts_has_more": false,
    "group": {"role": "linked", "main_id": 17493287}
  }
}

Поля ответа

• custom_fields — в том же формате, который принимает метод create.
• leads, contacts — первые 50 идентификаторов. *_has_more: true означает, что связей больше.

Ошибки

404 Company not found: <id> — компания не найдена.

Возвращает поля карточки компании, доступные в аккаунте. Используйте этот метод, чтобы определить, какие поля можно передать в custom_fields при создании компании.

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

{
  "status": true,
  "response": [
    {
      "id": 101,
      "name": "Телефон",
      "code": "PHONE",
      "type": "multitext",
      "is_api_only": false,
      "enums": [
        {"id": 1, "value": "WORK"},
        {"id": 2, "value": "MOB"}
      ]
    },
    {
      "id": 310,
      "name": "Отрасль",
      "code": null,
      "type": "select",
      "is_api_only": false,
      "enums": [
        {"id": 11, "value": "Производство"},
        {"id": 12, "value": "Торговля"}
      ]
    }
  ]
}

Возвращает пользователей аккаунта amoCRM. Идентификатор пользователя передаётся в параметре responsible_user_id.

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

{
  "status": true,
  "response": [
    {
      "id": 2320770,
      "name": "Иван Петров",
      "email": "ivan@example.com",
      "is_active": true,
      "is_admin": false
    }
  ]
}

Возвращают сделки по названию или контакты по имени. Применяются для получения entity_id перед прикреплением компании.

Параметры

Элемент выдачи

{
  "id": 123456,
  "name": "Поставка оборудования",
  "responsible_user_id": 2320770,
  "created_at": 1701094831,
  "pipeline_id": 7,
  "status_id": 142,
  "price": 150000
}

Прикрепляет компанию к сделке, контакту или к главной компании группы.

Параметры

Результат

• leads, contacts — компания прикрепляется к сделке или контакту в amoCRM. Ответ: {"status": true, "response": []}.
• companies — компания company_id становится дочерней для entity_id. Ответ содержит состав группы после изменения.

Пример

{
  "company_id": 29875277,
  "entity_type": "companies",
  "entity_id": 17493287
}

{
  "status": true,
  "response": {
    "main_id": 17493287,
    "linked": [4926915, 29875257, 29875277]
  }
}

Проверки

Перед прикреплением сервис проверяет наличие записей в amoCRM: для companies — обеих компаний, для leads и contacts — сделки или контакта. При отсутствии записи возвращается 404 Company not found, Lead not found или Contact not found.

Ошибки 422

Создаёт компанию с указанными полями и прикрепляет её к сделке, контакту или главной компании в рамках одного запроса.

Параметры

Элемент custom_fields

Каждый элемент — объект, в котором указывается ровно один идентификатор поля и хотя бы одно значение.

Пример

{
  "name": "ООО «Ромашка»",
  "entity_type": "leads",
  "entity_id": 123456,
  "responsible_user_id": 2320770,
  "tags": ["api"],
  "custom_fields": [
    {
      "field_code": "PHONE",
      "values": [
        {"value": "+70000000000", "enum_code": "WORK"}
      ]
    },
    {
      "field_code": "EMAIL",
      "value": "info@example.com",
      "enum_code": "WORK"
    },
    {"field_name": "ИНН", "value": "7700000000"},
    {"field_name": "Отрасль", "value": "Производство"}
  ],
  "ignore_missing_fields": true
}

{
  "status": true,
  "response": {
    "company_id": 31000001,
    "skipped_fields": [
      {"index": 2, "field": "ИНН", "reason": "not_found"}
    ]
  }
}

• skipped_fields — поля, отсутствующие в аккаунте; возвращается только при ignore_missing_fields: true. index — позиция элемента в custom_fields.
• При entity_type: companies ответ дополнительно содержит состав группы (main_id, linked).

Валидация запроса

До обращения к amoCRM запрос проверяется по правилам ниже. При нарушении возвращается 400; ключ ошибки указывает на элемент, например custom_fields.2.value.

• Тег — непустая строка до 255 символов.
• Элемент custom_fields содержит ровно один из ключей field_id, field_code, field_name и хотя бы один из value, values, enum_id. Другие ключи не допускаются.
• value — строка до 10 000 символов, число или true/false.
• values — массив из 1–50 значений или объектов {value, enum_code}.
• enum_id — идентификатор или массив до 50 идентификаторов.
• ignore_missing_fields — true/false или 1/0.

{
  "status": false,
  "error": {
    "message": {
      "custom_fields.0": [
        "Укажите одно из: field_id, field_code, field_name"
      ],
      "tags.1": ["Тег должен быть непустой строкой"]
    },
    "code": 400
  }
}

Ошибки

Исключает дочернюю компанию из группы либо открепляет компанию от сделки или контакта.

Параметры

Результат

• Без entity_type или с companies — дочерняя компания выходит из группы. Ответ: {"main_id": null, "linked": []}.
• leads, contacts — компания открепляется от сделки или контакта. Ответ: {"status": true, "response": []}.

Ошибки

Назначает дочернюю компанию главной в её группе. Прежняя главная компания становится дочерней.

Параметры

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

{
  "status": true,
  "response": {
    "main_id": 29875257,
    "linked": [4926915, 17493287]
  }
}

Ошибки