# FilingPulse — SEC EDGAR filings as normalized JSON

> FilingPulse is data infrastructure: a REST API, webhooks, and a hosted MCP server over U.S. SEC EDGAR filings, normalized to one frozen JSON schema. It reports what was filed and provides no interpretation, trading signals, or investment advice. Not affiliated with the U.S. Securities and Exchange Commission; source data is public domain.

Site: https://filingpulse.io · API base: https://api.filingpulse.io · MCP endpoint: https://mcp.filingpulse.io/mcp

## Datasets

- **Form 4 insider trades** (`/v1/insider-trades`): every Form 4 and 4/A, normalized from the ownership XML — reporting owners, non-derivative and derivative transactions, holdings, footnotes, remarks. Historical backfill extends the dataset continuously (coverage window is reported live by `GET /v1/health` and the MCP `get_dataset_status` tool).
- **8-K corporate events** (`/v1/events`): 8-K filings classified by the SEC's official item codes (e.g. 2.02 results of operations, 5.02 officer/director changes).
- **S-1/F-1 registration lifecycle** (`/v1/registrations`): registration statements, amendments, effectiveness notices, and priced prospectuses (S-1, S-1/A, F-1, F-1/A, EFFECT, 424B1, 424B4), threaded by SEC file number. Tracked live since 2026-08-01; no backfill for this vertical.

## Authentication

Pass an API key in the `X-API-Key` header. Free keys are self-serve at https://filingpulse.io/signup.html (email only, no card). `/v1/health` and `/v1/schema` need no key.

## Endpoints

- **GET /v1/insider-trades** — Form 4 / 4/A insider-transaction filings. Filters: ticker, cik, form_type, since / until (YYYY-MM-DD, both inclusive — together a fixed reproducible window), limit (max 200), offset (max 10,000). Newest filed first.
- **GET /v1/insider-trades/{accession}** — One Form 4 filing by SEC accession number.
- **GET /v1/events** — 8-K corporate events classified by official item code. Filters: ticker, cik, item, since, until, limit, offset.
- **GET /v1/registrations** — S-1/F-1 registration lifecycle events. Filters: stage (registration | amendment | effectiveness | prospectus), form_type, cik, file_number, since, until, limit, offset.
- **GET /v1/registrations/{accession}** — One registration event by accession number.
- **GET /v1/webhooks** — List your webhook subscriptions. POST creates one (event types: form4, event_8k, registration; the signing secret is shown once). DELETE /v1/webhooks/{id} deactivates; GET /v1/webhooks/{id}/deliveries is the delivery log.
- **GET /v1/health** — Public. Dataset counts and freshness, no key required.
- **GET /v1/schema** — Public. This schema contract as JSON, no key required.

Every list endpoint returns the envelope `{"data": [...], "total": n, "limit": n, "offset": n}`: `total` is the count of rows matching the filters; page by advancing `offset` by `limit` until `offset` >= `total`.

## Schema v1 — the frozen contract

Frozen 2026-07-23. v1 fields never change meaning or type. Evolution is additive only (new fields, new object types). Anything breaking requires a v2 namespace and a deprecation window.

Design rules:
- Values are strings exactly as filed — share counts, prices, and dates are never coerced to numbers or dates. Consumers coerce at their edge.
- Absent means null, never missing — every documented field is always present; null means 'not stated in the filing', empty lists/objects mean 'none'.
- The SEC accession number is the unique, stable identity of every filing.

### Object `form4`

One Form 4 / 4/A insider-transaction filing, normalized from the ownership XML. Returned by /v1/insider-trades.

- `accession` (string): SEC accession number — the unique, stable filing id (design rule 3). Use this (not source_url) to dedupe and to fetch /v1/insider-trades/{accession}. Merged at the API layer; added 2026-08-08.
- `filed_date` (string|null): Date EDGAR accepted the filing, normalized to YYYY-MM-DD from the feed timestamp — the value since= filters and list ordering use. A computed convenience field (a deliberate, clearly-marked exception to the as-filed rule). Merged at the API layer; added 2026-08-08.
- `form_type` (string): "4" or "4/A" as filed.
- `period` (string|null): Period of report, YYYY-MM-DD as filed.
- `amendment_date` (string|null): On 4/A only: date of the original submission being amended; null on originals.
- `issuer` (object): {name, cik, ticker} — all string|null, as filed.
- `reporting_owners` (array[object]): One reporting_owner per insider on the filing (multi-owner filings are common for funds).
- `transactions` (array[object]): All transaction rows, non-derivative first, then derivative.
- `holdings` (array[object]): Position statements with no transaction (holdings-only and mixed filings).
- `footnotes` (object): Footnote text keyed by id, e.g. {"F1": "..."}; whitespace-normalized.
- `remarks` (string|null): Free-text remarks field.
- `holdings_only` (boolean): true when the filing reports no transactions.
- `source_url` (string): EDGAR URL of the ownership XML this was normalized from.
- `normalized_by` (string): Parser version stamp.

### Object `form4.reporting_owner`

One insider on a Form 4.

- `name` (string|null): As filed (EDGAR convention is often LAST FIRST).
- `cik` (string|null): Owner CIK, zero-padded as filed.
- `is_director` (string|null): Filed as "1"/"0"/"true"/"false" — passed through as filed.
- `is_officer` (string|null): As filed (see is_director).
- `is_ten_pct_owner` (string|null): As filed (see is_director).
- `officer_title` (string|null): e.g. "Chief Executive Officer".

### Object `form4.transaction`

One transaction row (non-derivative or derivative table).

- `security_title` (string|null): e.g. "Class A Common Stock".
- `transaction_date` (string|null): YYYY-MM-DD as filed.
- `transaction_code` (string|null): SEC transaction code — see transaction_codes.
- `acquired_disposed` (string|null): "A" acquired / "D" disposed.
- `shares` (string|null): Share/unit count as filed.
- `price_per_share` (string|null): As filed; null is common on grants/awards.
- `shares_owned_after` (string|null): Post-transaction holdings.
- `ownership_type` (string|null): "D" direct / "I" indirect.
- `is_derivative` (boolean): true for derivative-table rows.
- `conversion_or_exercise_price` (string|null): Derivative rows; null on non-derivative.
- `exercise_date` (string|null): Derivative rows.
- `expiration_date` (string|null): Derivative rows.
- `underlying_security_title` (string|null): Derivative rows.
- `underlying_security_shares` (string|null): Derivative rows.
- `footnote_ids` (array[string]): Footnote ids referenced anywhere in this row; resolve via top-level footnotes.

### Object `form4.holding`

One holdings row (position statement without a transaction).

- `security_title` (string|null): As filed.
- `shares_owned` (string|null): As filed.
- `ownership_type` (string|null): "D" direct / "I" indirect.
- `nature_of_ownership` (string|null): e.g. "By Trust" — usually paired with indirect.
- `is_derivative` (boolean): true for derivative-table rows.
- `footnote_ids` (array[string]): Footnote ids referenced in this row.

### Object `event_8k`

One 8-K / 8-K/A filing classified by official item code, normalized from the SGML index headers. Returned by /v1/events.

- `accession` (string): SEC accession number — the unique, stable filing id (design rule 3). Use this (not source_url) to dedupe. Merged at the API layer; added 2026-08-17.
- `form_type` (string|null): "8-K" or "8-K/A".
- `period` (string|null): YYYYMMDD exactly as filed (SGML headers use this format; rule 1 — no reformatting).
- `filed_date` (string|null): YYYYMMDD as filed.
- `issuer` (object): {name, cik} — first filer block only (multi-filer 8-Ks keep the first; documented limitation).
- `items` (array[object]): [{code, caption}] — caption as filed; code is the official item number (e.g. "2.02") or null if the caption matches no known item.
- `source_url` (string): The -index-headers.html URL normalized from.
- `normalized_by` (string): Parser version stamp.

### Object `registration_event`

One Securities Act registration-lifecycle filing (S-1/F-1 registration, amendment, EFFECT effectiveness notice, or 424B1/424B4 priced prospectus), normalized from the SGML index headers. Returned by /v1/registrations. The SEC file number threads one offering across all its stages.

- `accession` (string): SEC accession number — the unique, stable filing id (design rule 3). Use this (not source_url) to dedupe and to fetch /v1/registrations/{accession}. Merged at the API layer; added 2026-08-17.
- `form_type` (string|null): S-1, S-1/A, F-1, F-1/A, EFFECT, 424B1, or 424B4.
- `stage` (string|null): Lifecycle stage: registration | amendment | effectiveness | prospectus.
- `filed_date` (string|null): YYYYMMDD as filed.
- `effectiveness_date` (string|null): YYYYMMDD as filed; set on EFFECT notices, null otherwise.
- `act` (string|null): Securities act, e.g. "1933 Act", as filed.
- `file_number` (string|null): SEC file number (e.g. "333-296288") — shared by the registration, its amendments, the EFFECT notice, and the final prospectus of one offering.
- `film_number` (string|null): EDGAR film number, as filed.
- `issuer` (object): {name, cik, sic, sic_code, state_of_incorporation, fiscal_year_end} — all string|null, first filer block only (co-registrant filings keep the first; documented limitation).
- `former_names` (array[object]): [{name, date_changed}] prior company names, as listed in the header (empty list when none).
- `source_url` (string): The -index-headers.html URL normalized from.
- `normalized_by` (string): Parser version stamp.

### Transaction codes (Form 4, as filed)

- `P`: Open-market purchase
- `S`: Open-market sale
- `A`: Grant/award from issuer
- `M`: Option exercise
- `F`: Shares withheld for tax on vesting/exercise
- `D`: Disposition to issuer (incl. going-private cash-outs)
- `G`: Gift
- `C`: Conversion of derivative
- `X`: In-the-money option exercise/expiration
- `J`: Other (see footnotes)

Notes:
- form4.accession and form4.filed_date were added 2026-08-08 (additive evolution): they are merged from the filing index at the API layer and appear on every API response and form4 webhook payload, including all historical rows.
- event_8k.accession and registration_event.accession were added 2026-08-17 (same additive API-layer merge): every object served by /v1/events, /v1/registrations, and 8k/registration webhook payloads now carries the accession, including all historical rows, so source_url is no longer the only stable per-filing id.
- Transaction codes are passed through verbatim from the filing; this API reports what was filed and provides no interpretation, signals, or investment advice.
- Full code list: SEC Forms 3/4/5 instructions.
- EFFECT notices do not state which form type they make effective, so effectiveness rows also cover non-tracked registrations (S-3, S-8, ...). Join on file_number to tie one to a tracked S-1/F-1.

## Common query patterns

Every request below is executed by the regression suite before it ships; the full annotated list is at https://filingpulse.io/patterns.html.

### Insider trades — Form 4

- Every insider filing for one company, newest first:
  `GET https://api.filingpulse.io/v1/insider-trades?ticker=PRTH`
- By CIK, when the ticker can't be trusted:
  `GET https://api.filingpulse.io/v1/insider-trades?cik=1841514`
- Amendments only — or originals only:
  `GET https://api.filingpulse.io/v1/insider-trades?form_type=4/A`
- One filing by its accession number:
  `GET https://api.filingpulse.io/v1/insider-trades/0001653558-26-000110`
- Incremental sync without re-downloading history:
  `GET https://api.filingpulse.io/v1/insider-trades?since=2026-08-01&limit=100`
  `GET https://api.filingpulse.io/v1/insider-trades?since=2026-08-01&limit=100&offset=100`

### Corporate events — 8-K

- Every filing that reports a leadership change:
  `GET https://api.filingpulse.io/v1/events?item=5.02`
- A digest of one event type over a window:
  `GET https://api.filingpulse.io/v1/events?item=5.07&since=2026-07-01`
- Everything one company reported:
  `GET https://api.filingpulse.io/v1/events?cik=793952`

### IPO registrations — S-1 / F-1

- New registration statements in a window:
  `GET https://api.filingpulse.io/v1/registrations?stage=registration&since=2026-07-28`
- One offering, first filing to pricing:
  `GET https://api.filingpulse.io/v1/registrations?file_number=333-297472`

### Across datasets

- One company across all three datasets:
  `GET https://api.filingpulse.io/v1/insider-trades?cik=1906364`
  `GET https://api.filingpulse.io/v1/events?cik=1906364`
  `GET https://api.filingpulse.io/v1/registrations?cik=1906364`

## Webhooks

Push delivery for new filings (live filings only — backfill never triggers a webhook). Subscriptions filter by event type (`form4`, `event_8k`, `registration`) plus tickers, 8-K item codes, registration stages, or file numbers. Deliveries are signed HMAC-SHA256 over the exact body in the `X-FilingPulse-Signature` header (per-subscription secret, shown once at creation); verify over the RAW request bytes. Failed deliveries retry at 60s / 5m / 30m / 2h.

## Rate limits and pricing (flat monthly subscriptions)

| Tier | Price | Requests/month | Requests/min | Webhooks |
|------|-------|----------------|--------------|----------|
| Free | $0 | 2,500 | 10 | 1 |
| Starter | $19/mo | 25,000 | 60 | 5 |
| Growth | $49/mo | 150,000 | 120 | 25 |
| Scale | $99/mo | 500,000 | 240 | unlimited |

Every tier gets the same data and the same schema — paid tiers buy volume, not access. Quotas reset 00:00 UTC on the 1st. If a subscription lapses the key drops to free-tier limits; it is never revoked.

## MCP server (for AI agents)

Hosted Model Context Protocol endpoint at `https://mcp.filingpulse.io/mcp` (streamable HTTP, no install): seven read-only tools — get_insider_trades, get_insider_filing, get_corporate_events, get_ipo_registrations, get_registration_event, get_dataset_status, get_schema. Anonymous access is a discovery tier (20 tool calls/min per IP, 25 rows/call); use a free REST key for volume. Per-client setup: https://filingpulse.io/mcp.html

## SDKs

- Python: `pip install filingpulse` — zero required dependencies, typed errors, webhook signature verification.
- JavaScript/TypeScript: `npm install filingpulse` — zero runtime dependencies (fetch + WebCrypto), ESM + CJS, full types.

## Pages

- https://filingpulse.io/docs.html — API reference
- https://filingpulse.io/patterns.html — Query patterns (CI-run copy-paste requests)
- https://filingpulse.io/recipes.html — Runnable example programs (Python + Node)
- https://filingpulse.io/mcp.html — MCP server setup
- https://filingpulse.io/signup.html — Get a key
- https://filingpulse.io/insider-trades/ — Per-ticker insider-trading pages
- https://filingpulse.io/registrations/ — S-1/F-1 registration pipeline
- https://filingpulse.io/changelog.html — Changelog
- https://filingpulse.io/about.html — About
- https://filingpulse.io/terms.html — Terms
- https://filingpulse.io/privacy.html — Privacy