# Company identity

Tickers are not stable identifiers. They are reassigned, they change at a merger
or rebrand, and the same string can mean different issuers in different decades.
The `/v1/identity` routes expose the mapping between tickers and issuers as
records with validity windows and a named source, rather than as a lookup that
silently returns today's answer.

## Two resolution routes

Arche has two routes that take a ticker and give you a company, and they are not
interchangeable:

- `/v1/edgar/companies:resolve` (identity only): Returns `cik`, `ticker`, `exchange` and `as_of`, and nothing else. It is the
  shortest path from a ticker to a CIK, and `exchange` is not currently
  populated on it. Use it inside a retrieval loop where you only need the key.
- `/v1/identity/resolve` (full record): Returns the whole identity record — including `company_name`, a populated
  `exchange`, the `company_id` the modeling routes need, the validity window,
  and the SEC filing the mapping came from. Use it when you need to show or
  audit the issuer, not just key off it.

If you are choosing between them and do not have a reason to prefer the first,
use `/v1/identity/resolve`. The extra fields cost nothing and one of them —
`company_id` — is required by routes you will reach later.

## Resolve a ticker

```bash
curl -X GET "https://api.arche.fi/v1/identity/resolve?ticker=MSFT" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

Representative response:

```json
{
  "data": {
    "as_of_date": "2026-09-20",
    "identity": {
      "id": "574477d5-0130-5abb-816c-52cd41c4571a",
      "company_id": "8f53593d-eae0-458d-9b33-7ed72325dd96",
      "cik": "0000789019",
      "ticker": "MSFT",
      "company_name": "MICROSOFT CORP",
      "exchange": "NASDAQ",
      "active_from": "2026-07-17",
      "active_to": null,
      "is_active": true,
      "source": "sec:company_submissions",
      "source_loaded_at": "2026-07-17T17:47:11Z",
      "source_filing_accession": "0001193125-26-380280",
      "confidence_score": null
    }
  }
}
```

`source_filing_accession` names the SEC submission the mapping was read from, so
an identity claim is traceable to a document rather than to a vendor list.

## Search by name

When you have a name rather than a symbol. The parameter is `query`, not `q` —
`q` is undeclared and would be ignored, returning an unfiltered page:

```bash
curl -X GET "https://api.arche.fi/v1/identity/search?query=microsoft&page_size=25" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

Results come back in the standard [paginated envelope](https://docs.arche.fi/pagination), each item
carrying the same identity record shown above.

## List mappings

Every mapping for one ticker, current and historical:

```bash
curl -X GET "https://api.arche.fi/v1/identity/tickers/AAPL" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

Every mapping for one issuer — the reverse question, and the one to ask when a
company has traded under more than one symbol:

```bash
curl -X GET "https://api.arche.fi/v1/identity/companies/0000789019" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

## Mapping validity

`active_from` and `active_to` bound the window in which Arche observed the
mapping. Read them as exactly that, and not as the dates the ticker began or
stopped trading:

- `active_from` is when the mapping was first observed in a load, not the
  listing date. A mapping that has always been true can still carry a recent
  `active_from` because that is when the load ran.
- `active_to` is set only once a later load showed the mapping had ended. It is
  `null` for a live mapping.
- `is_active` reflects the current state of the mapping.

> **Warning:** Do not use `active_from` as a corporate-history date. It is
> provenance for the mapping record, not a fact about the security. For a
> point-in-time question about what a ticker meant on a past date, pass
> `as_of` to `/v1/edgar/companies:resolve` rather than
> filtering these windows yourself.

## company_id vs cik

Arche uses two company keys and they are not interchangeable:

- `cik` (10-digit string): The SEC's own identifier, zero-padded. Every `/v1/edgar`, `/v1/coverage` and
  `/v1/fundamentals` route keys off it.
- `company_id` (uuid): Arche's internal company key. The `/v1/modeling` and `/v1/ai` routes key off
  this one instead, and will not accept a CIK.

`/v1/identity/resolve` returns both, which makes it the natural first call in a
pipeline that will touch [modeling](https://docs.arche.fi/modeling) later. `company_id` is `null`
when the filer is not in the company reference, so check it before passing it on.

## Next steps

- [Time series](https://docs.arche.fi/time-series): Pull a metric across a whole reporting history, point-in-time or as-reported.
- [Metric catalog](https://docs.arche.fi/metrics): Look up canonical and derived metric names, formulas, bundles and segments.
- [Modeling](https://docs.arche.fi/modeling): Snapshot-anchored ratios, growth, TTM aggregates and normalized model periods.