/api/v1/sec/entities

Return unique entity names, optionally filtered by filing form type.

Return unique entity names, optionally filtered by filing form type. Results are alphabetically sorted and cached for 5 minutes.

5 tokensSince v1.0.0

Why use this

Distinct-entity catalog endpoint — returns every unique `(entity_name, cik)` pair observed in the local filings index, alphabetically sorted, optionally filtered by form type. The right surface for: form-type-aware autocomplete ("only show entities that have actually filed a 10-K"), notification-rule builders (user picks form type → entity search shows only relevant filers), entity-pivot navigation in the SEC workstation. Server-side `Cache-Control: public, max-age=300` (5 min cache) — entity list mutates slowly so caching is safe; expect a 5-minute lag for newly-onboarded filers. Returns a non-standard envelope (`{status, data}` only — NO `request_id` or `timestamp`) because the handler builds its own `jsonify` for cache-header control rather than going through `ApiResponse.success()`.

Common use case

In notification settings, user selects a form type (e.g. 10-K), then a search bar appears where they can search for specific entities to watch. The autocomplete only shows entities that actually have filings of the selected form type. Also used in the SEC workstation for general entity search by company name.

Distinct-entity catalog — every unique (entity_name, cik) pair observed in the local filings index, alphabetically sorted. Optional form_type filter narrows to entities that have actually filed forms of that type — useful for form-type-aware autocomplete ("show me entities that file 13F-HR" returns ~6000 institutional managers; "show me entities that file 10-K" returns ~7000 issuers; "show me entities that file Form 4" returns ~80,000+ insiders). Cached server-side for 5 minutes via Cache-Control: public, max-age=300 — newly-onboarded filers will appear with up to 5-minute lag. Note the non-standard response envelope: {status, data} only — the handler bypasses ApiResponse.success() to control the cache header. For form-type catalog use GET /api/v1/sec/forms; for entity-CIK resolution from a ticker use GET /api/v1/scrapping/cik; for ticker-based lookups against the same entities use GET /api/v1/tickers/lookup (when available).

Parameters

Name	In	Required	Default	Allowed	Description	Example
form_type	query	optional	—	—	Filter to entities with filings of this type (`10-K`, `10-Q`, `8-K`, `4`, `13F-HR`, `13D`, `13G`, `S-1`, `20-F`, etc. — see [SEC EDGAR form types](https://www.sec.gov/forms)). If omitted, returns all entities across all form types. Case-sensitive — pass exactly as it appears in `data[].form_type` from `GET /api/v1/sec/forms`.	10-K

Response schema

Field	Type	Nullable	Description
status	string	no	Always `"success"` on 2xx. Note: this endpoint uses a custom `jsonify` envelope rather than `ApiResponse.success()` to control the `Cache-Control` header — so `request_id` and `timestamp` are NOT present (unlike sibling endpoints in this section).
data	array	no	Array of distinct entity records, sorted alphabetically by `entity_name` (case-sensitive — uppercase names sort before lowercase per default Postgres collation). One entry per unique `(entity_name, cik)` pair. Empty array when no filings match the filter — never null.
data[].entity_name	string	no	Filer's legal entity name as registered with SEC. Casing reflects EDGAR's stored form — typically uppercase for institutional filers (e.g. `BERKSHIRE HATHAWAY INC`, `BLACKROCK INC`), mixed-case for issuers (e.g. `Apple Inc.`, `Microsoft Corporation`). The same legal entity can appear with multiple cosmetic variants if EDGAR registrants update their formal name — dedupe client-side via `cik` if needed.
data[].cik	string	no	Filer CIK as a zero-padded 10-character string (e.g. `0000320193` for Apple). Stable across decades — same CIK refers to the same legal entity even if `entity_name` cosmetic variations exist. Use as the join key for follow-up queries against XBRL, 13F, or insider-filing tables.

Sample response

"status": "success"
"data":
]

}

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

Reveal credentials

curl "https://api.finradar.ai/api/v1/sec/entities?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).