--- title: "Resolve Companies by Identifier (Batch)" method: POST path: "/companies/resolve/" tags: ["Companies"] --- # Resolve Companies by Identifier (Batch) `POST /companies/resolve/` ## Request - Base URL: `https://api.financialreports.eu` - URL: `https://api.financialreports.eu/companies/resolve/` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer **Access Level Required:** Requires **Standard Access (Level 1)**. --- Reconcile a list of your identifiers against our coverage in one request. Each row may carry any mix of `isin`, `lei`, `cik`, `ticker` and `name`, plus an optional opaque `ref` echoed back so you can join results to your source rows. Results are returned in input order. **Resolution order** — ISIN, LEI, CIK, ticker, venue ticker, name. First hit wins, but every identifier you supply is evaluated: if two of them resolve to different companies the row comes back `ambiguous` with `identifier_conflict` and both in `candidates`, rather than us silently picking one. **A name alone never returns `matched`.** No matter how close the match, a name-only row caps at `ambiguous` and hands you candidates to choose from. Names are not identifiers, and asserting a match on one is how filings end up attached to the wrong issuer. **Venue-ticker matches are qualified, not asserted.** A ticker that only resolves through our security-listing data is cross-checked against the `name` you supplied. If they disagree you get `ambiguous` + `name_disagrees`; if you supplied no name we cannot corroborate at all, so you get `matched` carrying `security_listing_unverified` — trust that bucket accordingly. **A ticker is checked against your `name`, even on a single hit.** Tickers are reused across exchanges: if your name rules out the company holding the ticker as its primary one and backs a company holding it on another venue, that company is the match. When other companies hold the same ticker on other venues and nothing you sent rules them out, the row carries `multiple_tickers` and lists them in `candidates`, even on a `matched` row. Append an ISO country code (`WDI.DE`) to pin the exchange. **Billing** — one request is one call against your quota, whatever the row count. Rows we do not cover are not billed differently from rows we do. Maximum 500 rows per request. Up to 50 rows per request reach the name lookup, within 25 seconds; beyond either a row carrying only a name returns `not_covered` with `name_tier_skipped`, so split large name-heavy batches. ## Request body - CompanyResolveRequest - `rows` ResolveRow[], required: 1-500 rows to reconcile. - `ref` string: Opaque client-supplied key, echoed back untouched so results can be joined to source rows. Must be unique within the batch if supplied. Results are also returned in input order. - `isin` string - `lei` string - `cik` string: Accepted padded or bare: `CIK0000320193` and `320193` are equivalent. - `ticker` string: Separator-insensitive: `BRK.B`, `BRK-B` and `BRK B` are equivalent. May carry the market as an ISO country suffix (`01316.HK`, `VOLV B.SE`, `PETR4.BR`): the ticker is then matched only against companies listed in that market. - `name` string: Used to corroborate a ticker match, and as a last-resort candidate lookup. A name alone NEVER produces a `matched` result. ## Response `200` Reconciliation complete. Individual rows may still be unmatched. - CompanyResolveResponse: Deliberately not the paginated `{count, next, previous, results}` envelope: this is a single non-paginated POST action whose result set is exactly the request's rows, in the same order. - `summary` CompanyResolveSummary, required - `matched` integer, required - `matched_via_alias` integer, required: Rows resolved through a recorded former or alternative name. - `ambiguous` integer, required - `not_covered` integer, required - `results` CompanyResolveResult[], required - `ref` string, nullable, required: Echoed from the request row. - `input` object, required: The identifiers supplied for this row, echoed back. - `status` 'matched' | 'matched_via_alias' | 'ambiguous' | 'not_covered', required: * `matched` - Resolved to exactly one company * `matched_via_alias` - Name is a recorded former or alternative name of exactly one company * `ambiguous` - Several plausible companies — see candidates * `not_covered` - No company found - `resolved_via` union, required: Which identifier produced the match. Null unless `status` is `matched`. Also null for `matched_via_alias`, where the name produced it. * `isin` - ISIN * `lei` - Legal Entity Identifier * `cik` - SEC Central Index Key * `ticker` - Primary ticker * `security_listing` - Venue ticker via security listing - 'isin' | 'lei' | 'cik' | 'ticker' | 'security_listing': * `isin` - ISIN * `lei` - Legal Entity Identifier * `cik` - SEC Central Index Key * `ticker` - Primary ticker * `security_listing` - Venue ticker via security listing - unknown - `company` CompanyResolveMatch, required: The company payload on a resolve result. Purpose-built rather than reusing CompanyMinimalSerializer, which has no `ticker` -- unusable for a ticker-reconciliation endpoint. Every field here is already published on /api/companies/, so this adds no new public surface. - `id` integer, required: Unique company identifier. - `name` string, required: Company name. - `ticker` string, nullable, required: The company's primary ticker. Secondary share classes live on the security-listings endpoint, not here. - `isins` string[], required: Primary ISIN(s). Use the company detail endpoint for the full list. - `lei` string, required: Legal Entity Identifier (ISO 17442). - `country_code` string, nullable, required: ISO 3166-1 alpha-2 country code. - `listing_status` string, required: LISTED, DELISTED, SUSPENDED or UNKNOWN. - `candidates` CompanyResolveMatch[], required - `id` integer, required: Unique company identifier. - `name` string, required: Company name. - `ticker` string, nullable, required: The company's primary ticker. Secondary share classes live on the security-listings endpoint, not here. - `isins` string[], required: Primary ISIN(s). Use the company detail endpoint for the full list. - `lei` string, required: Legal Entity Identifier (ISO 17442). - `country_code` string, nullable, required: ISO 3166-1 alpha-2 country code. - `listing_status` string, required: LISTED, DELISTED, SUSPENDED or UNKNOWN. - `warnings` string[], required: Stable codes qualifying the result. `no_identifiers` - the row carried nothing to match on. `identifier_conflict` - two identifiers on this row resolved to different companies; both are in `candidates`. `name_disagrees` - a ticker matched but the supplied name shares no distinguishing token with ours, so the match is not asserted. `multiple_tickers` - the ticker maps to more than one company. On an `ambiguous` result they are the `candidates`; on a `matched` result the company holds it as its primary ticker and the `candidates` hold it on other venues. `security_listing_unverified` - matched on a venue ticker with no name supplied, so the match could not be corroborated. This code covers TWO distinct situations that cannot currently be told apart: the listing row may be one of the known ticker collisions, OR the ticker may since have been reassigned to a different issuer (security listings are not retired today). Supplying `name` resolves the first but not the second. `name_tier_skipped` - the per-request name-lookup budget was exhausted before this row; re-send it in a smaller batch. ## Other responses - `400`: Malformed batch — too many rows, no rows, or duplicate `ref` values. - `401`: Unauthorized - `403`: Your API plan does not include access to this endpoint. - `429`: Rate limit, plan quota or spend cap reached. --- [API](https://skmtc.dev/financialreports/apis/financialfilings-api.md) · [All operations](https://skmtc.dev/financialreports/apis/financialfilings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/financialreports/apis/financialfilings-api/revisions/55935bdabd20?raw)