Skip to content
/api/v1/cusip/search

Full-text search across CUSIP mappings.

Full-text search across CUSIP mappings. Searches CUSIP, ticker, and security name fields. Returns only valid (active) mappings with pagination.

1 tokensSince v3.14.0

Why use this

Full-text search across CUSIP / ticker / issuer-name fields — the right entrypoint for typeahead UIs that accept any of those three input shapes (e.g. user types `Apple` or `AAPL` or `037` and the search palette resolves all 3 into the same CUSIP). Built atop the same `cusip_security_catalog` (~26K rows) but with PostgreSQL trigram fuzzy matching on the issuer-name field. Returns only ACTIVE mappings (excludes superseded predecessors of corporate-action chains — for chain expansion use the dedicated [GET /api/v1/cusip/chain/{cusip}](/docs/reference-data/cusip-api/get-cusip-chain) entrypoint). Pagination via standard `limit + offset`.

Common use case

Building a CUSIP search interface where users can type partial input across any of the three fields. Also useful in 'reconcile a customer's free-form security mention against our canonical catalog' workflows — given user input `tesla` or `tesla motors`, return TSLA / `88160R101` / `TESLA INC` for downstream pipeline use.

Full-text search across the CUSIP catalog — accepts any of CUSIP / ticker / issuer-name as input and returns relevance-ranked matches. Built on PostgreSQL trigram fuzzy matching for the name field plus exact-prefix matching for CUSIP and ticker fields. The natural backend for typeahead search palettes that need to resolve partial user input into canonical CUSIP-shaped output. Returns only ACTIVE mappings — superseded predecessors of corporate-action chains are excluded (use GET /api/v1/cusip/chain/{cusip} for chain expansion). Relevance scoring: exact ticker match = 1.0, exact CUSIP match = 0.95, name-trigram-similarity = 0.30-0.85. Empty results array on no matches — does NOT 404. For exact-key lookups always prefer the keyed endpoints (/cusip/lookup/{cusip}, /cusip/ticker/{ticker}) — they're cheaper at the catalog-row level.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
qqueryrequired——Search query (matches CUSIP, ticker, or security name). Case-insensitive. Trigram fuzzy matching on the name field — `apple` matches `APPLE INC` AND `APPLE HOSPITALITY REIT`. CUSIP fragment matching is exact-prefix (so `037` matches `037833100` but `833` does not). Ticker matching is exact OR prefix on canonical hyphen form (`BRK` matches both `BRK-A` and `BRK-B`).apple
limitqueryoptional50—Max results returned (1-100). Server caps at 100 — values > 100 silently clamp to 100.20
offsetqueryoptional0—Pagination offset for chunked retrieval. Pair with `limit` for `total // limit` page count.0

Response schema

FieldTypeNullableDescription
resultsarraynoArray of matching catalog rows. Order: by relevance score DESC (exact ticker matches first, then exact CUSIP-prefix matches, then trigram name-similarity score). Empty array on no matches — does NOT 404.
results[].cusipstringno9-character CUSIP.
results[].tickerstringyesCanonical hyphen-form ticker. Null for unmapped securities.
results[].issuer_namestringnoIssuer name (all-caps EDGAR convention).
results[].security_groupstringyesSecurity classification — `Stocks` / `ETFs` / `Preferred` / `Warrants` / `Debt` / `Other`.
results[].cusip6stringno6-character CUSIP issuer prefix.
results[].scorenumbernoRelevance score in range [0, 1] — exact ticker match scores 1.0, exact CUSIP match scores 0.95, name-trigram similarity scores from 0.30-0.85 depending on overlap. Useful for client-side post-filtering (e.g. drop results below 0.40 to suppress weak matches).
metaobjectnoPagination block: `{ total: integer, limit: integer, offset: integer, query: string }`. `total` is the full match count across all pages — use for pagination control rendering.

Sample response

·
  • "results":
    ]
  • "meta":
    • "total": 2
    • "limit": 50
    • "offset": 0
    • "query": "apple"
    }
}

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/cusip/search?api_Token=YOUR_API_KEY" \
  -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).