Skip to content

Companies

The company store holds about 3.5 million Russian legal entities (registry data with OKVED activity code, region, size, revenue and headcount bands, status) plus a small set of well-known groups that exist only as directory entries without an INN. Two endpoints:

  • GET /v1/companies/search finds companies by name or by filters.
  • GET /v1/companies/{inn} returns the full card of one company.

Companies carry bands, not exact figures: no exact revenue or headcount is available.

GET /v1/companies/search

curl -s -H "Authorization: Bearer $TRRU_KEY" -G "https://trru.atapinar.com/v1/companies/search" \
  --data-urlencode "query=Газпром нефть" --data-urlencode "limit=2"

Parameters

Parameter Type Default Meaning
query string empty Company name, fuzzy. Cyrillic or Latin transliteration, either works. See Name search.
inn string empty Exact INN. Keep it a string: INNs can start with 0.
okved_prefix string empty OKVED code prefix, matched from the start: 20 (chemicals), 20.1, 46.75 (wholesale of chemical products). The dot is part of the code as stored.
region string empty Region as FNS code (77, 16) or as a name (Москва, Татарстан, moskva, Krasnodar). See Region resolution.
size_band string empty Exact value. Seen: micro, small, medium, large.
revenue_band string empty Exact value. Seen: lt_100m, 100m_1b, 1b_10b, gt_10b (rouble bands, from under 100 million to over 10 billion).
status string empty Exact value. Seen: active, liquidated.
only_active boolean false true keeps rows whose status is empty or starts with active (or the Russian equivalent of "operating"). Combine it with status only if you want to narrow further.
limit integer 25 Rows to return. Values above 100 are clamped to 100 without an error.

Filters combine with AND. At least one filter is required: a call with none of them returns 400 give at least one filter (query, inn, okved_prefix, region, ...). When query is the only filter but normalises to nothing (for example ООО or ab: only a legal-form word, which is stripped, or too short), the 400 message says so instead: query is too short or only a legal-form word (e.g. ООО, LLC) after normalisation; add a more distinctive word from the name or another filter (inn, okved_prefix, region, ...). A non-empty inn must be 10 or 12 digits, otherwise 400 inn must be 10 (legal entity) or 12 (individual) digits; a well-formed INN that is not in the store just returns no rows. Filters on bands, status and OKVED are exact or prefix matches and are not validated against a list: an unknown size_band returns 200 with no rows.

The headcount_band field in responses uses 0_15, 16_100, 101_250, 251_1000, gt_1000; there is no request filter for it.

query is normalised before matching, and so is every stored name: Cyrillic is transliterated to Latin, Turkish letters and accents are folded, punctuation is removed, and legal-form words (ООО, АО, ПАО, LLC, JSC, GmbH, A.Ş., Ltd Şti and similar) are dropped. Matching is trigram similarity between the two normalised strings. A name needs a similarity of at least 0.45 (0.3 for a query shorter than six normalised characters) to be returned.

Consequences:

  • Газпром нефть, Gazprom Neft and LLC Gazprom Neft are the same query.
  • The legal form is ignored: searching Лукойл returns ПАО "ЛУКОЙЛ" and unrelated small companies called ЛУКОЙЛ-… and ranks them by similarity.
  • It is a name match, not an identity match. A search for Gazprom returns several small ООО "ГАЗПРОМ" entities with score 1.0 before any large group. Always check okved, region, size_band and inn before treating a hit as the company you mean.
  • Very common names return many exact duplicates (ООО "РОГА И КОПЫТА" exists under several INNs). Add region or okved_prefix.

Results are ordered by name_score (when query is given), then by revenue_band as text, then id. The band ordering is alphabetical on the band code, not a size ranking: do not read the order of equal-score rows as largest first.

Region resolution

  • Digits are an FNS region code, left-padded to two digits: 77 Moscow, 78 Saint Petersburg, 16 Tatarstan, 23 Krasnodar Krai.
  • Anything else is matched against region names, either as written in Russian (Москва, Татарстан) or in the same Latin transliteration as names (moskva, Krasnodar). A name can match more than one region; all of them are searched.
  • Nothing matches: 400 unknown region 'xyz' — use an FNS code like 77 or a Russian name.

Result rows show the region as stored: either 77 Москва г (code and name) or just 77.

Speed

Name, INN and OKVED+region searches normally answer in 1 to 3 seconds. A filter that is not selective, such as size_band=large alone, can take around 10 seconds. Add a second filter (an OKVED prefix or a region) to keep calls fast.

Example response

Request: GET /v1/companies/search?query=Газпром нефть&limit=2 (URL-encoded in the real call).

{
  "data": {
    "rows": [
      {
        "id": 80,
        "inn": null,
        "ogrn": null,
        "name_ru": "Газпром нефть",
        "name_en": "Gazprom Neft",
        "okved": null,
        "region": null,
        "city": "Saint Petersburg",
        "size_band": null,
        "revenue_band": null,
        "headcount_band": null,
        "status": null,
        "website": "gazprom-neft.com",
        "origin_country": "RU",
        "as_of": "2026-10-20",
        "name_score": 1.0,
        "sanctioned_inn": false,
        "sanction_name_hits": [
          { "list": "OFAC", "name": "PUBLIC JOINT STOCK COMPANY GAZPROM NEFT", "sim": 1.0 },
          { "list": "UK", "name": "GAZPROM NEFT", "sim": 1.0 },
          { "list": "CSL", "name": "Public Joint Stock Company Gazprom Neft", "sim": 1.0 }
        ]
      },
      {
        "id": 2809927,
        "inn": "7751363900",
        "ogrn": "1257700252358",
        "name_ru": "ООО \"НЕФТЕГАЗПРОМ\"",
        "name_en": null,
        "okved": "46.76.3",
        "region": "77 Москва г",
        "city": null,
        "size_band": "micro",
        "revenue_band": "lt_100m",
        "headcount_band": "0_15",
        "status": "active",
        "website": null,
        "origin_country": "RU",
        "as_of": "2026-10-10",
        "name_score": 0.625,
        "sanctioned_inn": false,
        "sanction_name_hits": []
      }
    ],
    "row_count": 2,
    "truncated": false
  },
  "meta": {
    "sources": [
      { "source_id": "most", "fetched_at": "2026-11-12T22:46:29.632841+00:00", "as_of": "2026-10-20" },
      { "source_id": "eu_fsf", "fetched_at": "2026-11-13T06:15:29.885405+00:00", "as_of": null },
      { "source_id": "ofac_sdn", "fetched_at": "2026-11-13T06:16:10.754928+00:00", "as_of": null }
    ],
    "request_id": "d84af61b8b26464593e59091d605e43d",
    "truncated": false
  }
}

The first row is a directory entry: no INN, no registry fields. Such rows cannot be opened with /v1/companies/{inn}.

A filter-only search (no query) has no name_score. Request: GET /v1/companies/search?okved_prefix=20.1&region=Татарстан&only_active=true&limit=2; the first row of the real response:

{
  "id": 69745,
  "inn": "0278930432",
  "ogrn": "1170280034297",
  "name_ru": "ООО \"ЭКСА\"",
  "name_en": null,
  "okved": "20.14",
  "region": "16 Татарстан респ",
  "city": "Казань",
  "size_band": "micro",
  "revenue_band": "lt_100m",
  "headcount_band": "0_15",
  "status": "active",
  "website": null,
  "origin_country": "RU",
  "as_of": "2026-10-10",
  "sanctioned_inn": false,
  "sanction_name_hits": []
}

Field notes

Field Meaning
id Internal row id. Not an official identifier.
inn, ogrn Tax and registration numbers (strings). null for directory-only entries.
name_ru, name_en Names as held. name_ru usually includes the legal form.
okved Main activity code as stored, for example 46.76.3. null where unknown.
region, city Region (see above) and city when known.
size_band, revenue_band, headcount_band Bands only. null when the registry data has no figure.
status active, liquidated, or null when unknown.
origin_country Country code of the entity, RU for registry rows.
as_of Date of the registry snapshot the row comes from.
name_score Only with query: similarity of the normalised names, 0 to 1.
sanctioned_inn true when the row's INN is on an active entry of a sanctions list. Always false without an INN.
sanction_name_hits Up to three active sanctions entries whose normalised name is almost identical (similarity 0.8 or more), each with list, name, sim. Empty means no near-identical name.

Name hits need a human check

sanction_name_hits is a name coincidence check, not proof that the company is the listed one. ООО "НЕФТЕГАЗПРОМ" above is not Gazprom Neft. Verify with INN and details: see Sanctions and restrictions.

meta.sources lists the company registry source and the sanctions lists used for the flags.

Code

curl -s -H "Authorization: Bearer $TRRU_KEY" -G "https://trru.atapinar.com/v1/companies/search" \
  --data-urlencode "okved_prefix=20.1" --data-urlencode "region=Татарстан" \
  --data-urlencode "only_active=true" --data-urlencode "limit=10"

body = get("/v1/companies/search", okved_prefix="20.1", region="Татарстан", only_active="true", limit=10)
for c in body["data"]["rows"]:
    print(c["inn"], c["name_ru"], c["okved"], c["region"], c["revenue_band"])

const body = await get("/v1/companies/search", {
  okved_prefix: "20.1", region: "Татарстан", only_active: "true", limit: "10",
});
for (const c of body.data.rows) console.log(c.inn, c.name_ru, c.okved, c.region, c.revenue_band);

GET /v1/companies/{inn}

The full card of one company, looked up by INN.

curl -s -H "Authorization: Bearer $TRRU_KEY" "https://trru.atapinar.com/v1/companies/7708503727"
Parameter Type Default Meaning
inn (path) string required INN as a string, 10 digits for a legal entity.

INN tips

  • A legal entity has a 10-digit INN; a sole proprietor or private person has a 12-digit one. The company store is a register of legal entities, so look up 10-digit INNs. A 12-digit INN is accepted but normally returns 404.
  • The path value is format-checked: anything that is not exactly 10 or 12 digits (wrong length, letters, spaces inside) returns 400 inn must be 10 (legal entity) or 12 (individual) digits. Only a well-formed INN that is not in the store returns 404 no such company.
  • Keep the INN a string everywhere. Parsing it as a number drops a leading zero (0278930432 becomes 278930432) and the lookup then fails.
  • Some large entities exist only as directory entries without an INN (for example Sberbank). /v1/companies/7707083893 is 404 even though that INN appears in sanctions data. Find them with /v1/companies/search and use /v1/sanctions/check for screening.

Blocks of the card

Block Type Content
company object The registry row: identifiers (id, inn, ogrn, kpp), names, okved, region, city, bands, status, website, origin_country, as_of, fetched_at, source_id, plus extra (provenance notes and import flags of the registry feed) and a few technical fields (name_norm, content_hash, most_id, slug) that you can ignore.
other_rows_same_inn array Further rows with the same INN (at most 4), when the registry holds duplicates. Usually empty.
structure array Parent and child relations. Each row: relation, child_name, child_country, child_id, side. side is child for subsidiaries of this company and parent for its owners; on parent rows the child_* fields describe the parent company (same columns, reused). Up to 200 rows.
directory array Links to association or directory listings: most_id, name, kind, rtib_member, website. Up to 20 rows.
geo array Zero or one object: lat, lon, address.
people array Up to 50 people tied to the company: id, full_name, name_ru, name_tr, role, kind, country, source_id, as_of. Often empty.
sanctions object Screening result of the company's INN and name against the sanctions lists: query (name, inn, normalized), inn_hits, name_hits. Same shape as /v1/sanctions/check, with similarity at least 0.6 and active entries only, at most 5 name hits.

Rows of structure, directory and people shown above come from the query definition. The real card below has none of them, so the arrays are empty.

Contact details are admin-only

Email and phone style fields of people are returned only to keys with scope admin. For a data key they are removed: the keys are absent, not null.

Example response

Request: GET /v1/companies/7708503727

{
  "data": {
    "company": {
      "id": 2463744,
      "inn": "7708503727",
      "ogrn": "1037739877295",
      "kpp": "770801001",
      "name_ru": "ОАО \"РЖД\"",
      "name_en": null,
      "name_norm": "rzhd",
      "okved": "49.20.9",
      "region": "77",
      "city": null,
      "size_band": "large",
      "revenue_band": "gt_10b",
      "headcount_band": null,
      "status": "active",
      "website": null,
      "origin_country": "RU",
      "ru_status": null,
      "wikidata_id": null,
      "extra": {
        "source": "FNS GIR BO (bo.nalog.gov.ru); RFSD (Russian Financial Statements Database)",
        "in_segment": 1,
        "region_est": 0,
        "girbo_status": "ok"
      },
      "source_id": "most",
      "as_of": "2026-10-22",
      "fetched_at": "2026-11-12T22:35:58.587755+00:00",
      "content_hash": null,
      "most_id": "inn-7708503727",
      "slug": "inn-7708503727"
    },
    "other_rows_same_inn": [],
    "structure": [],
    "directory": [],
    "geo": [
      { "lat": 55.768871, "lon": 37.651807, "address": "г Москва, ул Новая Басманная, д 2/1 стр 1" }
    ],
    "people": [],
    "sanctions": {
      "query": { "name": "ОАО \"РЖД\"", "inn": "7708503727", "normalized": "rzhd" },
      "inn_hits": [
        {
          "list": "CSL",
          "entry_id": "34736",
          "name": "OPEN JOINT STOCK COMPANY RUSSIAN RAILWAYS",
          "entity_type": "entity",
          "program": "Non: RUSSIA-EO14024",
          "countries": ["RU"],
          "inn": "7708503727",
          "listed_on": null,
          "active": true,
          "delisted_on": null,
          "as_of": "2026-11-13"
        }
      ],
      "name_hits": [
        {
          "list": "CSL",
          "entry_id": "34736",
          "name": "OPEN JOINT STOCK COMPANY RUSSIAN RAILWAYS",
          "entity_type": "entity",
          "program": "Non: RUSSIA-EO14024",
          "countries": ["RU"],
          "inn": "7708503727",
          "listed_on": null,
          "active": true,
          "delisted_on": null,
          "as_of": "2026-11-13",
          "matched_name": "rzhd",
          "similarity": 1.0
        }
      ]
    }
  },
  "meta": {
    "sources": [
      { "source_id": "most", "fetched_at": "2026-11-12T22:46:29.632841+00:00", "as_of": "2026-10-22" },
      { "source_id": "us_csl", "fetched_at": "2026-11-13T06:17:04.741878+00:00", "as_of": "2026-11-13" }
    ],
    "request_id": "2d56c9ad09db48dd897218404ccd71cd",
    "truncated": false
  }
}

How to read it: the INN is on the US Consolidated Screening List (inn_hits, an exact identifier match), and the name matches the same entry (name_hits, similarity 1.0). Because both agree, this is a strong match. The sanctions block also appears for companies with no hit, with both arrays empty. How to interpret hits in general: Sanctions and restrictions.

Errors

Case Response
INN is not 10 or 12 digits (wrong length or non-numeric) 400 bad_request, message inn must be 10 (legal entity) or 12 (individual) digits
Well-formed INN not in the store 404 not_found, message no such company
Missing or bad key 401, see Errors 
{ "error": { "code": "not_found", "message": "no such company" } }

Code

curl -s -H "Authorization: Bearer $TRRU_KEY" "https://trru.atapinar.com/v1/companies/7708503727"

card = get("/v1/companies/7708503727")["data"]
print(card["company"]["name_ru"], card["company"]["okved"], card["company"]["revenue_band"])
print("sanctions INN hits:", [h["list"] for h in card["sanctions"]["inn_hits"]])

const { data: card } = await get("/v1/companies/7708503727");
console.log(card.company.name_ru, card.company.okved, card.company.revenue_band);
console.log("sanctions INN hits:", card.sanctions.inn_hits.map((h) => h.list));

Tips

  • To find buyers of a product, take the OKVED prefixes from buyers.mappings in /v1/products/{hs6} and pass them as okved_prefix here, with only_active=true and a region.
  • For a counterparty check, search by name, pick the right row by INN, then open the card by INN. See the Counterparty screening guide.
  • as_of tells how old the registry row is; the snapshot is not live.