/api/v1/xbrl/searchCompany name/ticker typeahead search
Search companies by ticker or name for autocomplete — a ranked typeahead over the fundamentals engine's company universe. Returns each match's ticker, company name and CIK.
Why use this
Common use case
The company name/ticker typeahead for the fundamentals engine — the discovery entry point you call first to turn what a user types into a concrete ticker, then hand that ticker to the statements, time-series or valuation endpoints. Matching is server-side over the always-current company catalog (sourced from the SEC's own company-tickers list, refreshed daily): a match on ticker (exact match boosted) OR company name (substring), ranked so the obvious hit leads — exact ticker first, then ticker prefixes, then name-contains, ties broken by ticker. Each row carries ticker, company (the entity name) and cik (10-char zero-padded). An empty or whitespace q returns an empty list rather than enumerating the whole universe (a typeahead with no query has no suggestions); limit bounds the result (default 10, capped at 50). Served at the cheapest tier (1 token) so it is safe on every keystroke. Errors: 400 INVALID_PARAM for a non-numeric or non-positive limit.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| q | query | optional | — | — | Free-text search across ticker (exact-match boosted) and company name (substring match). Case-insensitive. An empty or whitespace-only `q` returns an empty list (a typeahead with no query has no suggestions) — it never enumerates the whole universe and never errors. | apple |
| limit | query | optional | 10 | — | Maximum matches returned (capped at 50 server-side). 8-10 suits a typical autocomplete dropdown. A non-numeric or non-positive value -> 400 INVALID_PARAM. | 8 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| data | array | no | Matching companies, best-match first (exact ticker, then ticker prefix, then name-contains; ties by ticker ascending). Empty array when `q` is empty/whitespace or nothing matches. |
| data[].ticker | string | no | Canonical ticker (hyphen form). This is the identifier the other XBRL company endpoints accept as `{id}` / `ticker=`. |
| data[].company | string | no | Company (entity) name, for a human-readable autocomplete label. |
| data[].cik | string | no | Issuer CIK in 10-char zero-padded form. Useful as a join key against the SEC ownership / insider surfaces. |
| meta.count | number | no | Number of rows returned; `meta.query` echoes the trimmed search text. |
Sample response
- "status": "success"
- "data":
- "meta":
- "count": 2
- "query": "app"
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/xbrl/search?api_Token=YOUR_API_KEY&q=apple&limit=8" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).