API Documentation

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

Authentication

Pass your key in the X-API-Key header on every request. Unauthenticated requests receive 401; exceeding your tier's rate limit returns 429 with a Retry-After header.

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

Endpoints

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
`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
`limit` / `offset`	int	Pagination

GET /v1/health

Dataset counts and freshness. 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"]}}'

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.

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 lives in the repo as SCHEMA.md; 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.