> ## Documentation Index
> Fetch the complete documentation index at: https://octo-98895abd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Lookup

> Resolve a ticker, ISIN, CNPJ, fund name, or company name to the identifiers this API accepts.

### Overview

`lookup` turns something a human typed into something [`panel`](/api-docs/panel), [`quotes`](/api-docs/quotes) or [`funds`](/api-docs/funds) will accept. It searches B3 tickers, CVM funds and listed companies at once, and returns whatever matched, tagged with the key that matched it.

```sql theme={null}
api.lookup(p_query TEXT)
```

<Note>
  **Parameters, response columns and types are generated** from the SQL catalog and render
  under **Endpoints → Lookup** in the sidebar. This page carries what a schema cannot: what
  the matching actually does, and which columns are null on purpose.
</Note>

<Warning>
  **It does not invent identifier matches.** There is no ticker ↔ CNPJ join here. A query matching both a ticker and a listed company returns two rows, and whether they are the same entity is your call.
</Warning>

### What the matching does

| Population | Matching |
| - | - |
| Ticker | Exact, upper-cased and trimmed. No substring search. |
| ISIN | Exact, upper-cased and trimmed. |
| CNPJ | Non-digits stripped, then exact. Works for funds and companies. |
| `cd_cvm` | Exact, against the CVM company code. |
| Fund / company name | Case-insensitive **substring**. |

**Note**: because names are substrings, an empty string or a single common letter matches nearly everything and returns an arbitrary 20. Send something specific.

### Field notes

| Field | What to know |
| - | - |
| `id` | The identifier to use in other calls: a ticker, a 14-digit CNPJ, or a `cd_cvm`. |
| `id_type` | `ticker`, `cnpj`, or `cd_cvm` — tells you which endpoint accepts this `id`. |
| `asset_class` | For tickers the conservative B3 cash type; for funds the `entity_type`; `cia` for listed companies. |
| `name` | Nullable for funds whose registry name we do not hold. |
| `isin` | Tickers only; null for funds and companies. |
| `cnpj` | **Always null on ticker rows** — again, no invented ticker-to-issuer match. |
| `tickers` | A listed company's active B3 codes, from CVM's **published** FCA valores-mobiliários filing — never name-matched. Active means listed in the company's newest FCA with no end date **and** traded on the B3 cash market on at least 5 sessions in the last 30 days, so a thinly traded code is left out. `cia` rows only; null when the company has no active published listing. |

### Example

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X POST "$SILO_URL/rpc/lookup" \
    -H "apikey: $SILO_ANON_KEY" \
    -H "Content-Type: application/json" \
    -d '{"p_query":"PETR4"}'
  ```

  ```python Python theme={null}
  rows = requests.post(
      f"{URL}/rpc/lookup", headers=H, json={"p_query": "PETR4"}
  ).json()
  ```

  ```javascript JavaScript theme={null}
  const { data } = await supabase.rpc('lookup', { p_query: 'PETR4' })
  ```
</CodeGroup>

```json theme={null}
[
  { "id": "PETR4", "id_type": "ticker", "asset_class": "equity",
    "name": "PETROBRAS", "isin": "BRPETRACNPR6", "cnpj": null }
]
```

A name query spans populations, and a company row carries its tickers:

```json theme={null}
[
  { "id": "12345678000190", "id_type": "cnpj", "asset_class": "fidc",
    "name": "EXAMPLE FIDC MULTISETORIAL", "isin": null, "cnpj": "12345678000190" },
  { "id": "9512", "id_type": "cd_cvm", "asset_class": "cia",
    "name": "PETROLEO BRASILEIRO SA PETROBRAS", "isin": null,
    "cnpj": "33000167000101", "tickers": ["PETR3", "PETR4"] }
]
```

### Notes

* **At most 20 rows**, across all three populations combined.
* **No defined ordering.** If more than 20 match, which 20 you receive is arbitrary and may change between calls. Narrow the query — there is no offset that would help.
* Ticker rows span every cash-market BDI board, including BDR and fund-quota boards.
* No match returns `200 []` — the string matched nothing we hold, which is not the same as the entity not existing. Check spelling, then [`coverage`](/api-docs/coverage).


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