API: подсказки по организациям

Ищет компании и индивидуальных предпринимателей:

по ИНН, ОГРН и КПП;
названию (полному и краткому);
ФИО (для индивидуальных предпринимателей);
ФИО руководителя компании;
адресу до улицы.

Что умеет

✔️ Ищет по комбинации ИНН, названия и адреса в одном запросе («7736050003 Газ» → «ПАО Газпром», «вавилова сбер» → «ПАО Сбербанк»).

✔️ Находит конкретный филиал, если указать в запросе КПП («сбербанк 540602001» → «Сибирский банк ПАО Сбербанк»).

✔️ Понимает слитное и раздельное написание («альфабанк» = «Альфа-Банк»).

✔️ Ищет по частичному совпадению в ИНН / ОГРН («77094209» → «ООО Акварель») и названиях («росне» → «ПАО «НК «Роснефть»).

✔️ Подсказывает только организации или только ИП, или и тех и других. Умеет искать только в действующих или ликвидированных компаниях. Может ограничить подсказки кодом ОКВЭД или конкретным регионом России.

✔️ Учитывает, где вы находитесь (в связке с методом город по IP-адресу).

✔️ Возвращает основные реквизиты компании из ЕГРЮЛ: краткое и полное название, ОПФ, адрес, ОГРН, ИНН, КПП, ОКВЭД, статус организации, ФИО и должность руководителя.

✔️ В связке с методом организация по ИНН возвращает вагон дополнительной информации: количество сотрудников, все коды ОКВЭД, сведения о налоговой, ПФР и ФСС, документы и лицензии, учредители и руководители, финансовые показатели, реестр малого и среднего бизнеса.

❌ Для 25% компаний налоговая служба пока не сообщает КПП филиалов. Такие филиалы можно найти по ИНН, городу и улице филиала. Например, «7724261610 москва мясницкая» → «Филиал ФГУП "Почта России" (г Москва)».

Как вызвать

Чтобы вызвать метод, и подтвердите почту.

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

            
                POST https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/party
            
            
                
                    { "query": "сбербанк" }

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Token ${API_KEY}" \
  -d '{ "query": "сбербанк" }' \
  https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/party

// https://github.com/hflabs/dadata-csharp

var token = "${API_KEY}";
var api = new SuggestClientAsync(token);
var result = await api.SuggestParty("сбербанк");

// https://github.com/ekomobile/dadata
// Использует API-ключ из переменной окружения DADATA_API_KEY

import (
    "context"
    dadata "github.com/ekomobile/dadata/v2"
    "github.com/ekomobile/dadata/v2/api/suggest"
)

func main() {
    api := dadata.NewSuggestApi()
    params := suggest.RequestParams{Query: "сбербанк"}
    result, err := api.Party(context.Background(), &params)
}

var url = "https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/party";
var token = "${API_KEY}";
var query = "сбербанк";

var options = {
    method: "POST",
    mode: "cors",
    headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": "Token " + token
    },
    body: JSON.stringify({query: query})
}

fetch(url, options)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log("error", error));

// https://github.com/hflabs/dadata-php

$token = "${API_KEY}";
$dadata = new \Dadata\DadataClient($token, null);
$result = $dadata->suggest("party", "сбербанк");

# https://github.com/hflabs/dadata-py

from dadata import Dadata
token = "${API_KEY}"
dadata = Dadata(token)
result = dadata.suggest("party", "сбербанк")

Укажите при вызове:

Content-Type: application/json.
Accept: application/json.
${API_KEY} — API-ключ.

Тело запроса передавайте в кодировке UTF-8.

Параметры запроса

Название	Тип	Обяз.?	По умолч.	Описание
query	string	✓		Текст запроса
count	number		10	Количество результатов (максимум — 20)
type	string			Ограничение по типу организации
status	array [string]			Ограничение по статусу организации
okved	array [string]			Ограничение по коду ОКВЭД
locations	array [object]			Ограничение по региону или городу
locations_boost	array [object]			Приоритет города при ранжировании

Что в ответе

Объект с массивом подсказок в поле suggestions:

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

{
  "suggestions": [
    {
      "value": "ПАО СБЕРБАНК",
      "unrestricted_value": "ПАО СБЕРБАНК",
      "data": {
        "kpp": "773601001",
        "kpp_largest": null,
        "capital": null,
        "management": {
          "name": "Греф Герман Оскарович",
          "post": "ПРЕЗИДЕНТ, ПРЕДСЕДАТЕЛЬ ПРАВЛЕНИЯ",
          "start_date": 1254690000000,
          "disqualified": null
        },
        "founders": null,
        "managers": null,
        "predecessors": null,
        "successors": null,
        "branch_type": "MAIN",
        "branch_count": 88,
        "source": null,
        "qc": null,
        "hid": "145a83ab38c9ad95889a7b894ce57a97cf6f6d5f42932a71331ff18606edecc6",
        "type": "LEGAL",
        "state": {
          "status": "ACTIVE",
          "actuality_date": 1564012800000,
          "registration_date": 677376000000,
          "liquidation_date": null
        },
        "opf": {
          "type": "2014",
          "code": "12247",
          "full": "Публичное акционерное общество",
          "short": "ПАО"
        },
        "name": {
          "full_with_opf": "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО \"СБЕРБАНК РОССИИ\"",
          "short_with_opf": "ПАО СБЕРБАНК",
          "latin": null,
          "full": "СБЕРБАНК РОССИИ",
          "short": "СБЕРБАНК"
        },
        "inn": "7707083893",
        "ogrn": "1027700132195",
        "okato": "45293554000",
        "oktmo": "45397000000",
        "okpo": "00032537",
        "okogu": "4100104",
        "okfs": "41",
        "okved": "64.19",
        "okveds": null,
        "authorities": null,
        "documents": null,
        "licenses": null,
        "finance": null,
        "address": {
          "value": "г Москва, ул Вавилова, д 19",
          "unrestricted_value": "117312, г Москва, Академический р-н, ул Вавилова, д 19",
          "data": { ... }
        },
        "phones": null,
        "emails": null,
        "ogrn_date": 1029456000000,
        "okved_type": "2014",
        "employee_count": null
      }
    },
    ...
  ]
}

Название	Описание
Базовые поля
value	Наименование компании
unrestricted_value	= value

data.inn	ИНН
data.kpp	КПП
data.kpp_largest	КПП крупнейшего налогоплательщика
data.ogrn	ОГРН
data.ogrn_date	Дата выдачи ОГРН
data.hid	Внутренний идентификатор в Дадате
data.type	Тип организации LEGAL — юридическое лицо INDIVIDUAL — индивидуальный предприниматель

data.name	Наименование
└ full_with_opf	— полное наименование
└ short_with_opf	— краткое наименование
└ latin	— не заполняется
└ full	— полное наименование без ОПФ генерируется на основе full_with_opf, может содержать ошибки
└ short	— краткое наименование без ОПФ генерируется на основе short_with_opf, может содержать ошибки

data.fio	ФИО индивидуального предпринимателя
└ surname	— фамилия
└ name	— имя
└ patronymic	— отчество
└ gender	не заполняется
└ source	не заполняется
└ qc	не заполняется

	Коды статистики (только для действующих головных организаций и ИП):
data.okato	Код ОКАТО
data.oktmo	Код ОКТМО
data.okpo	Код ОКПО
data.okogu	Код ОКОГУ
data.okfs	Код ОКФС

data.okved	Код ОКВЭД
data.okved_type	Версия справочника ОКВЭД (2001 или 2014)

data.opf	Организационно-правовая форма
└ code	— код ОКОПФ
└ full	— полное название ОПФ
└ short	— краткое название ОПФ
└ type	— версия справочника ОКОПФ (99, 2012 или 2014)

data.management	Руководитель
└ name	— наименование руководителя (для юрлиц) или ФИО руководителя (для физлиц)
└ post	— должность руководителя (для физлиц)
└ start_date	— дата вступления в должность руководителя

data.branch_count	Количество филиалов
data.branch_type	Тип подразделения MAIN — головная организация BRANCH — филиал

data.address	Адрес
└ value	— адрес одной строкой: адрес организации для юридических лиц; город проживания для индивидуальных предпринимателей. стандартизован, поэтому может отличаться от записанного в ЕГРЮЛ.
└ unrestricted_value	— адрес одной строкой (полный, с индексом) стандартизован, поэтому может отличаться от записанного в ЕГРЮЛ.
└ data	— гранулярный адрес
└ data.source	— адрес одной строкой как в ЕГРЮЛ
└ data.qc	— код проверки адреса 0 — адрес распознан уверенно 1 или 3 — требуется ручная проверка

data.state	Состояние
└ actuality_date	— дата последних изменений
└ registration_date	— дата регистрации
└ liquidation_date	— дата ликвидации
└ status	— статус организации ACTIVE — действующая LIQUIDATING — ликвидируется LIQUIDATED — ликвидирована BANKRUPT — банкротство REORGANIZING — в процессе присоединения к другому юрлицу, с последующей ликвидацией
└ code	— детальный статус

Дополнительные поля, заполняются только через метод «Организация по ИНН»
data.employee_count	Среднесписочная численность работников
data.okveds[ ]	Коды ОКВЭД дополнительных видов деятельности
data.authorities	Сведения о налоговой, ПФР и ФСС
data.citizenship	Гражданство ИП
data.founders[ ]	Учредители компании
data.managers[ ]	Руководители компании
data.predecessors[ ]	Правопредшественники компании
data.successors[ ]	Правопреемники компании
data.capital	Уставной капитал компании
data.finance	Налоговый режим, доходы, расходы, долги и штрафы
data.documents	Документы и реестры
data.licenses[ ]	Лицензии
data.phones[ ]	Телефоны
data.emails[ ]	Адреса эл. почты
data.invalid	Признак недостоверных сведений об организации

Не заполняются
data.source
data.qc

Источники данных:

Коды ответа на запрос

HTTP-код ответа	Описание
200	Запрос успешно обработан
400	Некорректный запрос (невалидный JSON или XML)
401	В запросе отсутствует API-ключ
403	В запросе указан несуществующий API-ключ Или не подтверждена почта Или исчерпан дневной лимит по количеству запросов
405	Запрос сделан с методом, отличным от POST
413	Слишком большая длина запроса или слишком много условий
429	Слишком много запросов в секунду или новых соединений в минуту
5xx	Произошла внутренняя ошибка сервиса

Примеры вызова

Заголовки и параметры

Фильтр: действующая / ликвидирована

Фильтр: компания / ИП

Фильтр: головная компания / филиал

Фильтр по ОКВЭД

Фильтр по региону

Приоритет города при ранжировании

Ограничения

Количество условий в параметрах locationsи locations_boost — не более 10.

Длина запроса (параметр query) — не более 300 символов.

Количество запросов в день — в соответствии с тарифным планом.

Максимальная частота запросов — 30 в секунду с одного IP-адреса.

Максимальная частота создания новых соединений — 60 в минуту с одного IP-адреса.

Частые вопросы

Как часто обновляется справочник компаний (ЕГРЮЛ)?

По мере поступления обновлений от налоговой службы. Отставание от сайта налоговой (egrul.nalog.ru) не более 3 дней.

Почему не находится организация? Я точно знаю, она должна быть

Скорее всего, организация недавно зарегистрирована в ФНС, и мы еще не успели получить информацию о ней из налоговой. Отставание Дадаты от сайта налоговой (egrul.nalog.ru) не более 3 дней, так что организация скоро появится.

Подсказки не работают: ошибка 403 Forbidden (Feature SUGGESTIONS disabled for token)

Возможные причины:

Не подтверждён адрес эл. почты. Проверьте в личном кабинете. Если почта не подтверждена — посмотрите почтовый ящик и папку «спам», там должно быть письмо от «Дадаты».
В запросе указан неправильный API-ключ. Проверьте в личном кабинете
Исчерпан лимит запросов на день. Проверьте в личном кабинете

Что будет, если превысить 10 000 бесплатных запросов в день?

Подсказки перестанут подсказывать ツ До начала нового дня, затем снова заработают.

10 000 запросов считаются суммарно по всем видам подсказок: адреса, ФИО, организации, банки, емейлы...

Стоимость

Бесплатно до 10 тысяч запросов в день. Больше — в составе годовой подписки.