/api/v1/cusip/batchBatch CUSIP resolution.
Batch CUSIP resolution.
5 tokensSince v1.0.0
Why use this
Bulk CUSIP→ticker resolution — pass up to 1,000 CUSIPs in one request and receive ticker, issuer name, security group classification, and CUSIP6 (issuer prefix) for each. The hot-path enrichment endpoint for 13F holdings normalization workflows: 13F filings deliver positions as 9-character CUSIPs, but downstream analytics need tickers. Backed by FinRadar's `cusip_security_catalog` (~26K rows post-v3.11.0 expansion). Returns 6 security-group buckets: Stocks, ETFs, Preferred, Warrants, Debt, Other — useful for filtering 13F books to common-stock-only views without per-row decisions. Single-CUSIP variants (`/cusip/lookup/{cusip}`) exist but cost more per row at scale; this batch endpoint is the right choice for any multi-CUSIP workflow.
Common use case
Resolving all holdings in a large portfolio in a single request.
Batch CUSIP→ticker resolution — pass up to 1,000 CUSIPs and receive ticker, issuer name, security_group, and CUSIP6 (issuer prefix) for each. Backed by the cusip_security_catalog (~26K rows post v3.11.0). Six security_group buckets: Stocks, ETFs, Preferred, Warrants, Debt, Other. Hot-path for 13F enrichment, holdings normalization, and bulk reconciliation.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| cusips | body | required | — | — | Array of 9-character CUSIP strings (max 1,000 per request — server returns 400 above the cap; for larger universes split into multiple batches client-side). 8-char CUSIPs (missing check digit) are zero-padded server-side. Whitespace and case are normalized. Order is preserved in the response so client code can zip results back to inputs. | ["037833100","594918104"] |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| results | array | no | One row per requested CUSIP, in INPUT ORDER (not sorted) — so client code can safely zip the response array back against the request array. Unmapped CUSIPs still produce a row (with null `ticker` / `issuer_name` / `security_group`) so output length always matches input length. |
| results[].cusip | string | no | Echoed 9-character CUSIP (post-normalization — leading whitespace stripped, padded to 9 chars if input was 8). Use for index-matching against the input array when needed. |
| results[].ticker | string | yes | Resolved canonical ticker (hyphen form). Null when (a) the CUSIP is not in our `cusip_security_catalog` (~3% of legacy 13F filings), (b) the security has no ticker (debt, private placements), or (c) the issuer was delisted before our enrichment ran. For chain-aware multi-CUSIP-per-ticker tracking use `/cusip/chain/{cusip}`. |
| results[].issuer_name | string | yes | Issuer name from the canonical catalog (typically all-caps EDGAR convention for SEC-registered issuers; varies for international issuers). Null when the CUSIP is unmapped. Use for human-readable rendering rather than the raw `cusip` itself. |
| results[].security_group | string | yes | Security classification — one of `Stocks` (common equity), `ETFs` (exchange-traded funds), `Preferred` (preferred stock), `Warrants`, `Debt` (bonds, notes), `Other` (REITs, partnership units, etc.). Null when the catalog entry exists but security_group is not yet enriched. Filter 13F holdings to `Stocks` only for clean common-equity flow analysis. |
| results[].cusip6 | string | no | First 6 characters of the CUSIP — the ISSUER PREFIX (a single legal issuer can have multiple 9-char CUSIPs across share classes / debt issues, all sharing the same `cusip6`). Useful for grouping multi-class issuers. Always present even when the full 9-char CUSIP is unmapped. |
| meta | object | no | Resolution-rate metadata: `{ requested: integer, resolved: integer, unmapped: integer }`. `resolved + unmapped == requested`. A high `unmapped` count (>10%) suggests the input batch contains stale/legacy CUSIPs — try with chain-expansion via `/cusip/chain/{cusip}` per-row to chase corporate-action successors. |
Sample response
·
- "results":
- "meta":
- "requested": 2
- "resolved": 2
- "unmapped": 0
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 -X POST "https://api.finradar.ai/api/v1/cusip/batch?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).