API Documentation

Base URL: https://api.filingpulse.io · All responses are JSON · Interactive OpenAPI explorer at /docs

Authentication

No key yet? Get one by email — the free tier takes under a minute. Pass your key in the X-API-Key header on every request. Unauthenticated requests receive 401. Two limits apply per tier: a per-minute rate limit (429 with Retry-After) and a monthly request quota (429 with X-Quota-Limit / X-Quota-Used headers). Monthly quotas reset at 00:00 UTC on the 1st.

curl https://api.filingpulse.io/v1/insider-trades?ticker=KMI \
  -H "X-API-Key: fp_your_key"

SDKs

Official clients for Python and JavaScript/TypeScript. Both are zero-dependency, ship typed errors (AuthError, NotFoundError, RateLimitError with the retry delay), and include constant-time webhook signature verification.

Python — `pip install filingpulse`

Version 0.2.0 covers the full API: insider trades, 8-K events, S-1/IPO registrations, and webhook CRUD.

from filingpulse import FilingPulse

fp = FilingPulse(api_key="fp_your_key")

for filing in fp.insider_trades(ticker="KMI", since="2026-07-01")["data"]:
    owner = filing["reporting_owners"][0]["name"]
    for tx in filing["transactions"]:
        print(owner, tx["transaction_code"], tx["shares"])

# Follow one securities offering across its lifecycle — S-1, amendments,
# effectiveness, prospectus — threaded by SEC file number:
for event in fp.registrations(file_number="333-298113")["data"]:
    print(event["filed_date"], event["form_type"], event["stage"])

JavaScript / TypeScript — `npm install filingpulse`

Built on fetch + WebCrypto: Node 18+, Deno, Bun, and browsers. ESM and CommonJS, fully typed. The published release (0.1.0) covers insider trades, 8-K events, and webhook CRUD; for /v1/registrations, call the REST endpoint with plain fetch until 0.2.0 reaches npm.

import { FilingPulse } from "filingpulse";

const fp = new FilingPulse("fp_your_key");
const { data } = await fp.insiderTrades({ ticker: "KMI", since: "2026-07-01" });

Package pages: PyPI · npm. Source lives in the API repository under sdk/. Complete runnable programs — CSV export, 8-K digests, a signature-verifying webhook receiver, IPO threading — are on the Recipes page, each one exercised against a live API instance in our test suite.

Exploring from Postman? Import the collection — every endpoint prewired with key auth, example filter values, and per-parameter docs, generated from this API's own OpenAPI spec.

OpenBB Platform — `pip install openbb-filingpulse`

A provider extension for the OpenBB Platform: FilingPulse plugs into the standard insider_trading endpoint, one row per transaction leg as reported on the filing, with accession grouping the legs of one filing. start_date/end_date map to this API's since=/until= filters, so a fixed window returns the same population forever. Set your key once as the filingpulse_api_key credential.

from openbb import obb

obb.user.credentials.filingpulse_api_key = "fp_your_key"

result = obb.equity.ownership.insider_trading(
    symbol="KMI", provider="filingpulse",
    start_date="2026-07-01", end_date="2026-07-31",
)
df = result.to_df()

Package page: PyPI. Numbers are coerced to floats for the OpenBB standard model; for the exact as-filed strings, use the REST API or SDKs above.

Using an AI agent instead of writing code? The same data is served over a hosted MCP server — no key required to explore.

Endpoints

Reference below; the Query patterns page shows the most common parameter combinations as copy-paste requests, each one executed by our regression suite.

GET /v1/insider-trades

Form 4 insider transactions, newest filed first.

param	type	meaning
`ticker`	string	Issuer trading symbol (case-insensitive)
`cik`	string	Issuer CIK (leading zeros optional)
`form_type`	`4` \| `4/A`	Originals only, or amendments only
`since`	YYYY-MM-DD	Only filings filed on/after this date
`until`	YYYY-MM-DD	Only filings filed on/before this date — with `since`, a fixed reproducible window
`limit` / `offset`	int	Pagination (limit ≤ 200, default 50)

Response: {"data": [FilingObject…], "total": n, "limit": n, "offset": n}

GET /v1/insider-trades/{accession}

One filing by SEC accession number (e.g. 0001506307-26-000083).

GET /v1/events

8-K corporate events, classified by official item code.

param	type	meaning
`item`	e.g. `2.02`	Item code filter (2.02 = earnings, 5.02 = officer changes, 1.01 = material agreements…)
`cik`	string	Filer CIK
`since`	YYYY-MM-DD	Only events filed on/after this date
`until`	YYYY-MM-DD	Only events filed on/before this date
`limit` / `offset`	int	Pagination

GET /v1/registrations

S-1/IPO registration lifecycle events: registration statements (S-1, F-1), pre-effective amendments (S-1/A, F-1/A), SEC effectiveness notices (EFFECT), and final priced prospectuses (424B1, 424B4). The SEC file number (e.g. 333-296288) is shared across every stage of one offering — filter on it to follow a single deal from first filing to pricing.

param	type	meaning
`stage`	`registration` \| `amendment` \| `effectiveness` \| `prospectus`	Lifecycle stage
`form_type`	e.g. `S-1`, `424B4`	Exact form type
`file_number`	e.g. `333-296288`	One offering across all its stages
`cik`	string	Filer CIK
`since`	YYYY-MM-DD	Only events filed on/after this date
`until`	YYYY-MM-DD	Only events filed on/before this date
`limit` / `offset`	int	Pagination

Note: an EFFECT notice does not state which form it makes effective, so stage=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. GET /v1/registrations/{accession} returns a single event.

GET /v1/health

Dataset counts and freshness. No authentication required.

GET /v1/schema

The complete schema-v1 contract as machine-readable JSON: every object, field type, design rule, the list-response envelope, and the transaction-code table. Static and versioned — fetch it at build time for codegen or contract tests. No authentication required.

Webhooks

Create a subscription and FilingPulse POSTs each matching filing to your endpoint as it lands — no polling.

curl -X POST https://api.filingpulse.io/v1/webhooks \
  -H "X-API-Key: fp_your_key" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hook",
       "events": ["form4"],
       "filters": {"tickers": ["KMI", "AAPL"]}}'

Event types: form4 (filter: {"tickers": […]}), 8k (filter: {"items": ["2.02", …]}), and registration (filters: {"stages": […]} and/or {"file_numbers": ["333-296288", …]} — subscribe to a specific offering and get pinged at each lifecycle stage).

The response includes a secret (shown once). Every delivery is signed: X-FilingPulse-Signature: sha256=HMAC_SHA256(secret, raw_body). Verify before trusting:

import hashlib, hmac

def verify(secret: str, body: bytes, signature: str) -> bool:
    digest = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, f"sha256={digest}")

Failed deliveries retry at 1m, 5m, 30m, and 2h before being marked failed. Inspect delivery history at GET /v1/webhooks/{id}/deliveries.

No-code route: importable n8n templates wire these webhooks (signature verification included) to Slack, Discord, or anything else n8n connects to.

endpoint	action
`POST /v1/webhooks`	Create subscription (returns secret once)
`GET /v1/webhooks`	List your subscriptions
`DELETE /v1/webhooks/{id}`	Deactivate
`GET /v1/webhooks/{id}/deliveries`	Delivery log

Schema guarantees

The full field-by-field contract is served machine-readable at GET /v1/schema; the load-bearing rules:

rule	meaning
Strings as filed	Numeric values are never coerced — share counts and prices arrive exactly as filed. Coerce at your edge.
Null, never missing	Every documented field is always present; `null` means "not stated in the filing." No existence checks needed.
Additive evolution	v1 fields never change meaning or type. New fields may appear; existing ones are frozen.
Accession = identity	The SEC accession number is the unique, stable id for every filing.

Common Form 4 transaction codes

code	meaning
`P` / `S`	Open-market purchase / sale
`A`	Grant or award from the issuer
`M`	Option exercise
`F`	Shares withheld for tax
`G`	Gift
`D`	Disposition to the issuer

Codes are passed through verbatim from the filing. FilingPulse does not interpret them into signals or recommendations of any kind.