Authentication & Rate Limits

All API requests require a valid token and are subject to usage limits.

Authentication

Authenticate every request by including your API token in the X-WF-Auth-Token header. Tokens are issued by Windfall and tied to your organization's account.

Example Header

curl -X POST https://api.windfalldata.com/v1/ \
  -H "Content-Type: application/json" \
  -H "X-WF-Auth-Token: YOUR_API_TOKEN" \
  -d '{ ... }'

Keep your token secure

Never expose your API token in client-side code or public repositories. All requests must be made over HTTPS.

API Tokens

Each token is issued with a set number of usage tokens that correspond to the number of records you can query. The token allocation and refresh frequency are determined by your purchase order.

Token quota Per your purchase order

Refresh cadence Per your purchase order

Sandbox Tokens

Sandbox tokens are issued separately from production tokens and are prefixed with sandbox_. They authenticate against the sandbox endpoint only and do not consume credits.

Endpoint https://api.windfalldata.com/sandbox/v1

Token prefix sandbox_

Billing Non-billed

Production and sandbox tokens are not interchangeable — using a sandbox token on the production endpoint (or vice versa) returns 403. See the Sandbox page for details.

Rate Limits

The API enforces a rate limit to ensure fair usage and service stability.

Max requests 5 / second

Typical response time < 1 second

Exceeding the rate limit returns a 429 status with a rate_limit error. Back off and retry after a brief delay.

Error Responses

400 Malformed request body. Ensure your JSON is valid.

401 Invalid or missing API token. Check your X-WF-Auth-Token header.

403 Wrong token type for the endpoint (sandbox token on production, or production token on sandbox).

429 Rate limit exceeded. Wait and retry.