Skip to content
/api/v1/xbrl/search

Company 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

One cheap (1 token) call resolves free text to companies: matches on ticker (exact match boosted) and company name (substring), ranked exact-ticker first, then ticker-prefix, then name-contains. The 1-token cost makes it safe to call on every keystroke. Use it to power a ticker picker before drilling into [GET /api/v1/xbrl/companies/{id}/statements](/docs/company-data/company-financials-xbrl-as-filed/get-api-v1-xbrl-companies-id-statements), [GET /api/v1/xbrl/timeseries](/docs/company-data/company-financials-xbrl-as-filed/get-api-v1-xbrl-timeseries) or [GET /api/v1/xbrl/companies/{id}/valuation](/docs/company-data/company-financials-xbrl-as-filed/get-api-v1-xbrl-companies-id-valuation); the returned `ticker` is the input those endpoints expect, and `/xbrl/coverage` tells you whether a given match has parsed data yet.

Common use case

Building a company search / ticker autocomplete box in your own app.

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

NameInRequiredDefaultAllowedDescriptionExample
qqueryoptionalFree-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
limitqueryoptional10Maximum 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

FieldTypeNullableDescription
dataarraynoMatching 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[].tickerstringnoCanonical ticker (hyphen form). This is the identifier the other XBRL company endpoints accept as `{id}` / `ticker=`.
data[].companystringnoCompany (entity) name, for a human-readable autocomplete label.
data[].cikstringnoIssuer CIK in 10-char zero-padded form. Useful as a join key against the SEC ownership / insider surfaces.
meta.countnumbernoNumber of rows returned; `meta.query` echoes the trimmed search text.

Sample response

·
  • "status": "success"
  • "data":
    ]
  • "meta":
    • "count": 2
    • "query": "app"
    }
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected 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).