API Documentation - Board Scan

Getting Started

Authentication

Board Scan uses API key authentication. Include your key in the Authorization header with every request.

Keep your API key secure. Never expose it in client-side code or public repositories. Rotate it from your account settings if it is compromised.

HTTP

GET /alerts HTTP/1.1
Host: boardscan.com
Authorization: Bearer your_jwt_token
Content-Type: application/json

Authentication

All authenticated endpoints require a JWT Bearer token obtained from POST /auth/login. Pass the token in the Authorization header on every request. Tokens expire after 7 days.

Base URL

All API requests must be made over HTTPS to the following base URL:

Base URL

https://boardscan.com

All API requests must be made over HTTPS. We will provide at least 90 days notice before deprecating any endpoint.

Rate Limits

Rate limits are applied per API key. Exceeding the limit returns a 429 Too Many Requests response with a Retry-After header indicating seconds until reset.

Plan	Requests / Minute	Requests / Day
Authenticated endpoints	60	Fair use
Auth endpoints (login, signup)	10	Per IP

Error Handling

Errors return standard HTTP status codes alongside a JSON body describing the problem.

JSON

{
  "error": {
    "code": "director_not_found",
    "message": "No director with ID dir_abc123 found in your subscription scope.",
    "status": 404
  }
}

Common status codes:

200 Success
400 Bad Request - invalid parameters
401 Unauthorized - missing or invalid API key
429 Too Many Requests - rate limit exceeded
404 Not Found - resource does not exist

Endpoints

Alerts

Retrieve structured board change alerts extracted from SEC DEF 14A proxy filings. Each alert represents a new proxy filing with extracted company, director, and filing metadata.

Method	Path	Description
GET	/alerts	List alerts for your subscribed products
GET	/alerts/export	Export alerts as CSV (requires active subscription)
GET	/feed/boardscan	RSS 2.0 feed of recent board change alerts (public)

GET /alerts

Returns a list of board change alerts for your active subscriptions.

Parameter	Type	Required	Description
productId	string	Optional	Filter to a specific product (e.g., `boardscan`)
limit	integer	Optional	Max records to return. Default: 50.

cURL

curl https://boardscan.com/alerts \
  -H "Authorization: Bearer your_jwt_token" \
  -G \
  --data-urlencode "product_id=boardscan" \
  --data-urlencode "limit=25"

Response

[
  {
    "id": "alert_abc123",
    "product_id": "boardscan",
    "title": "Microsoft Corp (MSFT): Proxy Statement Filed",
    "source_id": "def14a-0000789019-26-000056",
    "content": "Company: Microsoft Corp\nTicker: MSFT\nFiled: 2026-04-15...",
    "created_at": "2026-04-15T09:14:22Z"
  }
]

CSV Export

Export all board change alerts for your subscription as a structured CSV file. Requires an active paid subscription.

Method	Path	Description
GET	/alerts/export	Download alerts as CSV (up to 1,000 records)

cURL

curl https://boardscan.com/alerts/export \
  -H "Authorization: Bearer your_jwt_token" \
  -G \
  --data-urlencode "product_id=boardscan" \
  -o board_changes.csv

Webhooks

Register HTTPS endpoints to receive real-time change events as they are extracted from new proxy filings.

Method	Path	Description
GET	/webhooks	List registered webhook endpoints
POST	/webhooks	Register a new webhook endpoint
DELETE	/webhooks/:id	Remove a webhook endpoint

Webhook Payload

Payloads are delivered as authenticated HTTPS POST requests. Verify the payload using the timestamp field before processing.

JSON Payload

{
  "product": "boardscan",
  "productName": "Board Scan",
  "alertCount": 2,
  "alerts": [
    {
      "sourceId": "boardex-dir-114829-2026-04-18",
      "title": "Acme Corp (ACME): Board Change",
      "summary": "Jane Doe joined the board as Independent Director. CRSP 30d: +3.2%. Inst. Signal: Accumulating."
    }
  ],
  "timestamp": "2026-04-19T14:22:00Z"
}

Guides

Quick Start

Get from zero to your first board change alert in under five minutes.

Step 1: Authenticate

Sign up at boardscan.com/signup and log in. Your JWT token is returned at login and used as the Bearer token in all API requests. Retrieve it from your account settings.

Step 2: Fetch recent board changes

Python

import requests

jwt_token = "your_jwt_token_here"
headers = {"Authorization": f"Bearer {jwt_token}"}

# Get recent board change alerts
response = requests.get(
    "https://boardscan.com/alerts",
    headers=headers,
    params={
        "productId": "boardscan",
        "limit": 25
    }
)

alerts = response.json()
for alert in alerts:
    print(f"{alert['title']} - {alert['created_at']}")

Step 3: Register a webhook

Python

response = requests.post(
    "https://boardscan.com/webhooks",
    headers=headers,
    json={
        "url": "https://yourapp.com/webhooks/boardscan",
        "productId": "boardscan",
        "events": ["alert"]
    }
)
webhook = response.json()
print(f"Webhook created: {webhook['id']}")

Need help? Email [email protected] or visit our support page for integration assistance.