> ## Documentation Index
> Fetch the complete documentation index at: https://docs.itoflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find and resolve symbols

> List exchanges, search by ticker or company, and resolve broker symbols, ISINs and MICs to Itoflow symbols.

> [!TIP]
>
> **The easiest way: ask your AI assistant.** With [Itoflow MCP](https://docs.itoflow.ai/mcp/install.md) connected to Claude or Codex, paste:
>
> ```text theme={null}
> Use Itoflow to find the Itoflow symbol for ASML on Euronext Amsterdam and for
> the ISIN US0378331005.
> ```
>
> > [card] [Open in Claude](https://claude.ai/new?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20find%20the%20Itoflow%20symbol%20for%20ASML%20on%20Euronext%20Amsterdam%20and%20for%20the%20ISIN%20US0378331005.)
> >
> > Start this in Claude with the Itoflow plugin.
>
> > [card] [Open in ChatGPT](https://chatgpt.com/?q=Use%20the%20Itoflow%20plugin%20\(https%3A%2F%2Fgithub.com%2Fitoflow%2Fskills\)%20for%20this.%20If%20it%20isn't%20installed%20yet%2C%20first%20tell%20me%20how%20to%20install%20it%20and%20sign%20in%20to%20Itoflow%2C%20and%20wait%20until%20I%20confirm.%20Then%3A%0A%0AUse%20Itoflow%20to%20find%20the%20Itoflow%20symbol%20for%20ASML%20on%20Euronext%20Amsterdam%20and%20for%20the%20ISIN%20US0378331005.)
> >
> > Start this in ChatGPT with the Itoflow plugin.
>
> Using another client? Copy the prompt with the button on the code block.
>
> No tokens or code needed. You can also do this in the [Itoflow app](https://app.itoflow.ai/chat). The rest of this page covers the HTTP API.

An Itoflow symbol is a ticker and an exchange code joined by a dot, such as `AAPL.US` or `ASML.AS`. Every endpoint that takes an instrument expects this form. `GET /symbols/exchanges` lists the exchange codes.

```mermaid theme={null}
flowchart TD
  Input[What you have] --> Choice{Which kind?}
  Choice -->|Ticker or company name| Search[Search]
  Choice -->|Full Itoflow symbol| Exact[Search with mode exact]
  Choice -->|ISIN, MIC or broker symbol| Resolve[Resolve]
  Resolve --> Result{Evidence agrees?}
  Result -->|Yes| Canonical[One Itoflow symbol]
  Result -->|No| Failure[422 with the reason]
```

## Search by ticker or company

`GET /symbols/search` returns ranked matches. Pass the ticker or company name in `q`, and optionally an `exchange` code:

```bash theme={null}
curl --fail-with-body --silent --show-error --get \
  'https://api.itoflow.ai/symbols/search' \
  --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \
  --data-urlencode 'q=AAPL' \
  --data-urlencode 'exchange=US'
```

To check that a full symbol exists, pass it with `mode=exact`:

```bash theme={null}
curl --fail-with-body --silent --show-error --get \
  'https://api.itoflow.ai/symbols/search' \
  --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \
  --data-urlencode 'q=AAPL.US' \
  --data-urlencode 'mode=exact'
```

## Resolve identifiers

`GET /symbols/resolve` turns other identifiers into an Itoflow symbol. Give it whatever you know, using these query parameters: `siq_symbol` (an Itoflow symbol), `ticker`, `broker_symbol`, `isin`, `company_name`, `currency`, `exchange` and `mic`. `exchange` takes an Itoflow code such as `US` or `LSE`; put a venue such as XNAS in `mic` (an ISO 10383 code), not in `exchange`.

The more you give, the more it can check. If the pieces disagree, are incomplete, or name an exchange Itoflow doesn't cover, it returns `422` with one of these codes: `identifier_evidence_missing`, `exchange_or_mic_required`, `canonical_currency_missing`, `instrument_identifier_conflict`, `instrument_identity_unresolved`, `unsupported_exchange` or `unsupported_mic`. The last two include the values Itoflow does support. Show that list to your user rather than guessing another exchange or currency.

Both resolve routes accept common share-class spellings in `ticker` or an unqualified `broker_symbol`. With `exchange: "US"`, `BRK.B`, `BRK/B` and `BRK B` resolve to `BRK-B.US` only when that dashed listing exists. This rule applies on every supported exchange: letters, one dot, slash or space, then one or two letters. Other shapes, such as `BAC.PRL`, are looked up as written. `BRKB` and `UHALB` stay unresolved; the resolver does not guess where to split them. Any supplied security identifier, currency or company name must still match the listing.

### Resolve many identifiers at once

`POST /symbols/resolve/batch` resolves up to 3,000 instruments in one call, such as every row of a holdings file. Each item takes the same fields as the `GET /symbols/resolve` query:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  'https://api.itoflow.ai/symbols/resolve/batch' \
  --header "Authorization: Bearer $ITOFLOW_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"items": [{"ticker": "AAPL", "exchange": "US"}, {"isin": "US5949181045"}, {"ticker": "QQQ", "mic": "XNAS"}]}'
```

The answer has one row per item, in the order you sent them, each with its `index`. A row answers as `GET /symbols/resolve` would: `ok: true` with the `instrument`, or `ok: false` with one of the codes above. One bad row does not fail the others. A row with `resolution_unavailable` was not finished within this call, for example because a data provider was slow; send those rows again. A fault that sending a row again would not fix, such as a database failure, fails the whole call.

Search and resolve may look up a data provider. If the provider is down they can fail with `5xx`; retry a few times with a growing wait.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.