# `POST /data/company`

**Purpose:** Resolve one company by **`ticker`**, **`cik`**, **`dart_corp_code`**, **`edinet_code`**, **`lei`**, or **`uscc`** and return its identity plus a coverage summary — every `form_type × fiscal_year × quarter` we hold for that issuer. To find a company by name, use [`POST /data/company/search`](/documents/post-datacompanysearch.md).

**Request:**

| Field | Type | Required | Notes |
|-------|------|----------|--------|
| `ticker` | string | Conditional | Exactly one of `ticker`, `cik`, `dart_corp_code`, `edinet_code`, `lei`, or `uscc` must be provided. 1–32 characters; case-insensitive. European tickers are the composite form `<ticker>_<country>` (e.g. `VIRI_F`); China A-share tickers are `<6-digit code>_CN` (e.g. `600519_CN`). |
| `cik` | string | Conditional | Numeric string; leading zeros optional. SEC-listed companies only. |
| `dart_corp_code` | string | Conditional | Numeric string; leading zeros optional. Korean DART-listed companies only. |
| `edinet_code` | string | Conditional | EDINET issuer code (`E` + 5 digits). Japanese EDINET-listed companies only. |
| `lei` | string | Conditional | 20-character ISO 17442 LEI; case-insensitive. European ESEF-listed companies only. |
| `uscc` | string | Conditional | 18-character Unified Social Credit Code; case-insensitive. China A-share companies only. |

**Response:**

| Field | Meaning |
|-------|---------|
| `ticker`, `cik`, `dart_corp_code`, `edinet_code`, `lei`, `uscc`, `legal_name` | Company identity. Only the applicable identifier is present — `cik` for SEC-listed companies, `dart_corp_code` for Korean companies, `edinet_code` for Japanese companies, `lei` for European companies, `uscc` (Unified Social Credit Code, 18 chars) for China A-share companies; the others are omitted. `legal_name` may be absent for rare records. |
| `jurisdiction` | `"US"` for SEC-listed companies; `"KR"` for Korean DART-listed companies; `"JP"` for Japanese EDINET-listed companies; `"EU"` for European ESEF-listed companies; `"CN"` for China A-share companies. |
| `sec_filings_url` | EDGAR public browse URL for the company, derived from CIK. Omitted for companies with no CIK (e.g. Korean and Japanese companies). |
| `sec_filings_urls` | SEC-listed companies only: one entry per CIK the company has filed under, current first — `{cik, is_current, url}`. |
| `tickers` | Every symbol the company has traded under — `{ticker, is_current, valid_from, valid_to}`; `valid_from` / `valid_to` only when set. |
| `dart_filings_url` | DART public browse URL for the company, derived from `dart_corp_code`. Omitted for companies with no DART corp code (e.g. US and Japanese companies). |
| `edinet_filings_url` | EDINET public browse URL for the company, derived from `edinet_code`. Omitted for companies with no EDINET code (e.g. US and Korean companies). |
| `esef_filings_url` | filings.xbrl.org public browse URL for the company, derived from `lei`. Omitted for companies with no LEI. |
| `cninfo_filings_url` | cninfo public browse URL for the company, derived from the 6-digit stock code. Omitted for non-A-share companies. |
| `filings_count` | Total filings we hold for this company across all forms, within your plan's history window. |
| `coverage` | Object keyed by filing-type name. **US**: SEC form names (`"10-K"`, `"10-Q"`, `"20-F"`, `"40-F"`). **KR** / **JP** / **EU** / **CN**: jurisdiction-neutral labels (`"annual"`, `"quarterly"`). Each value has `fiscal_years` (sorted list), `earliest`, `latest`, `fiscal_year_quarters` (year → list of quarter labels: `"FY"`, `"Q1"`–`"Q4"`), and `normalized_form` — a uniform identifier (`"annual"` / `"quarterly"`) you can use to iterate across jurisdictions without checking the key. |
| `credits_used` | Always **8** when successful. |

**Charging:** A `DATA_COMPANY_NOT_FOUND` response is still charged 8 credits.

**Errors:**

| HTTP | `error_code` | When |
|------|----------------|------|
| 404 | `DATA_COMPANY_NOT_FOUND` | No company on file for the given identifier. **Still debits 8 credits.** |
| 403 | `PLAN_TIER_INSUFFICIENT_COVERAGE` | The requested company is outside your plan's coverage scope. **Still debits 8 credits.** |
| 402 | `CREDITS_INSUFFICIENT` | Not enough credits. |
| 422 | — | Validation (zero or more than one of `ticker`/`cik`/`dart_corp_code`/`edinet_code`/`lei`/`uscc` supplied; non-numeric `cik` or `dart_corp_code`; `lei` not 20 letters or digits; `uscc` not 18 letters or digits). |

**Example Request:**

```json
{
  "ticker": "AAPL"
}
```

**Example Response:**

```json
{
  "ticker": "AAPL",
  "jurisdiction": "US",
  "cik": "0000320193",
  "legal_name": "Apple Inc.",
  "sec_filings_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=&dateb=&owner=include&count=40",
  "tickers": [
    {"ticker": "AAPL", "is_current": true}
  ],
  "filings_count": 12,
  "coverage": {
    "10-K": {
      "fiscal_years": [2020, 2021, 2022, 2023, 2024],
      "earliest": 2020,
      "latest": 2024,
      "fiscal_year_quarters": {
        "2020": ["FY"],
        "2021": ["FY"],
        "2022": ["FY"],
        "2023": ["FY"],
        "2024": ["FY"]
      },
      "normalized_form": "annual"
    },
    "10-Q": {
      "fiscal_years": [2023, 2024],
      "earliest": 2023,
      "latest": 2024,
      "fiscal_year_quarters": {
        "2023": ["Q1", "Q2", "Q3"],
        "2024": ["Q1", "Q2", "Q3"]
      },
      "normalized_form": "quarterly"
    }
  },
  "credits_used": 8,
  "sec_filings_urls": [
    {"cik": "0000320193", "is_current": true, "url": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=0000320193&type=&dateb=&owner=include&count=40"}
  ]
}
```