Identifier lookup

GET/api/v3/reference/lookup

Plan: Pro and up
Price: 3 credits per call
MCP tool: reference_lookup

REVERSE IDENTIFIER LOOKUP — give it a CUSIP, ISIN, SEDOL, ticker, estimate-vendor ticker, gvkey, regulator filer number, entity id or private-company-graph id and it returns the security (or, for an ISSUER key, every security under that issuer) plus which rung matched and whether that binding is still current. Exactly one identifier per call. RETIRED identifiers resolve by default — most of the bindings on file are retired, which is precisely why a stale identifier in your own data still lands, and it comes back with the date it was replaced and by what. Issuer keys NEVER nominate one security: an issuer can carry a common line, other share classes and a foreign listing, so all of them are returned and the grain is stated. Use it to turn a CUSIP-keyed custodian file into tickers, to find the ticker behind a regulator filing, or to audit whether an identifier in your own data has gone stale. Rung coverage is measured in every response (coverage.dataset.rung_fill_pct): CUSIP9 and CUSIP8 on every security, the other rungs on fewer.

Parameters

Query

cusipstringOptional

9 or 8 characters resolve a SECURITY; 6 characters are an ISSUER key and return every security under it. Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

isinstringOptional

Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

sedolstringOptional

Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

tickerstringOptional

Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

ibticstringOptional

Estimate-vendor ticker. Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

gvkeystringOptional

ISSUER key. Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

cikstringOptional

Regulator filer number — an ISSUER key. Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

entity_idstringOptional

This API's issuer entity id. Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

private_company_idstringOptional

Private-company-graph id — returns the listed issuer it bridges to, if any. Send exactly one of cusip, isin, sedol, ticker, ibtic, gvkey, cik, entity_id or private_company_id: the call is refused without it.

permnostringOptional

Research-grade security number (1-7 digits): every link to an issuer with its valid_from/valid_to dates, the link covering today, and that issuer's securities with the linked one flagged; the source's as_of is its newest link date (monthly)

include_retiredbooleanOptional

Also match identifiers that have been RETIRED.

Defaulttrue

Response

A 200 is a JSON envelope: ok: true and this endpoint's own fields (see Reference Data). It carries X-Request-ID, the credit headers (X-Credits-Cost, X-Credits-Remaining, X-Credits-Receipt, X-Credits-Settlement) and the rate-limit headers.

A 200 is billed even when it holds no data (an empty list, null, found: false), so check those fields. Pricing & credits explains the credit headers.

Errors

No error is billed. The body is { "ok": false, "error", "detail", "request_id" }; read the code from error.

Error	Meaning
`400 invalid_ticker`	The request is malformed, for example a ticker that is not a symbol: `invalid_ticker`, refused before any credit is reserved, with `param` naming the parameter. Not billed.
`401 unauthorized`	Missing or invalid API key.
`402 plan_required`	Your plan does not include this tool, you are out of credits, or your workspace's spend cap paused its keys. `plan_required` names the plan that unlocks the tool; `usage_exceeded` means the credit balance is spent; `spend_cap_reached` means the key is paused until the cap resets or is raised: `detail` names the cap and the reset, `cap_usd` and `resets_at` (ISO 8601) carry them, and `doc_url` links pricing and credits. Not billed.
`403 scope_denied`	This API key is limited to some products and this tool is not one of them. `product` names the tool's product and `scopes` the key's products. An upgrade does not change it: use a key whose scopes include the product, or change this key's scopes. Not billed.
`404 not_found`	No such resource. Not billed.
`422 validation`	A parameter is missing, out of range or the wrong type; `param` names it. Not billed.
`429 rate_limited`	Your plan's rate limit is spent for this window. Retry after `Retry-After` seconds. Not billed.
`503 paid_data_unavailable`	The data could not be served completely right now; retry later. Not billed.
`504 request_timeout`	The request ran past the server's time budget; retry. Not billed.

This table lists what the spec declares for this route. Error responses lists every code FIRM sends, with when to retry.

Guides

Read the Reference Data guide for this endpoint's fields and examples.

Request

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/reference/lookup?cusip=30231G102"

Response

No captured response for this route yet. A success is a JSON object with ok: trueand this route's own fields. For those, see the description above and the Reference Data guide.