/api/v1/filers/{cik}/metadataResolve exact-CIK filer identity and eligibility
Return the SEC registrant name, canonical filer-page slug, and completed-13F eligibility for one exact CIK. Authenticated but unmetered. This endpoint does not follow unified-holder primary/alternate CIK groupings and does not mutate holder data.
freeSince 3.147.0
Why use this
Use this server-side before rendering or canonicalizing a `/filer/` page. `isInstitutionalFiler=false` is an authoritative not-a-filer state; `identityStatus=registrant_missing` is a typed neutral identity and is distinct from a query or transport failure.
Common use case
Render the SEC's own registered name for CIK 0001067983, redirect a stale filer slug to the backend-owned canonical slug, or return 404 when that exact CIK has no completed 13F-HR/13F-HR/A in FinRadar's corpus.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| cik | path | required | — | — | One to ten decimal digits. The response always returns the canonical ten-digit zero-padded CIK. Empty, prefixed, punctuated, and overlength values return 400. | 0001067983 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| cik | string | no | Exact route CIK in canonical ten-digit zero-padded form. |
| identityStatus | string | no | `ok` when `sec.registrants.name` is a nonblank string; `registrant_missing` when the registry row/name is absent or unusable. Query failures return 5xx instead of this status. |
| registrantNameRaw | string | yes | Name stored in the SEC registrant record, preserved verbatim. Null only for `registrant_missing`. |
| displayName | string | no | Current UI spelling. Equal to the SEC name for `ok`; neutral `CIK <10-digit-cik>` for `registrant_missing`. |
| slug | string | no | Backend-owned lowercase ASCII canonical slug ending in the ten-digit CIK. Digits, legal suffixes, and SEC disambiguators are preserved as identity input. |
| isInstitutionalFiler | boolean | no | True only when this exact padded CIK has a completed `13F-HR` or `13F-HR/A` filing. It never follows holder aliases, alternate CIKs, or names. |
| holderUuid | string | yes | Optional compatibility link from an exact-CIK completed filing. Failure or absence of this non-authoritative lookup yields null without changing identity or eligibility. |
Sample response
·
- "status": "success"
- "data":
- "cik": "0001067983"
- "identityStatus": "ok"
- "registrantNameRaw": "Berkshire Hathaway Inc"
- "displayName": "Berkshire Hathaway Inc"
- "slug": "berkshire-hathaway-inc-0001067983"
- "isInstitutionalFiler": true
- "holderUuid": null
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/filers/0001067983/metadata" \
-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).