generated: '2026-08-14'
method: searched
source: >-
  https://api-docs.windfall.com/authentication/ (HTTP 200) +
  https://api-docs.windfall.com/sandbox/ (HTTP 200) +
  https://api-docs.windfall.com/examples/ (HTTP 200) +
  openapi/_original/windfall-openapi-original.json
docs: https://api-docs.windfall.com/
docs_last_updated: '2026-04'
authentication:
  style: api-key
  header: X-WF-Auth-Token
  transport: HTTPS only
  ref: authentication/windfall-authentication.yml
idempotency:
  supported: false
  note: >-
    No idempotency-key header or param is documented. Enrichment is a read-style
    lookup (POST body carries the query record); repeat calls return the same
    deterministic result in the sandbox and a fresh lookup in production.
pagination:
  supported: false
  note: Single-record real-time enrichment; there are no collection/list endpoints.
versioning:
  style: uri-path
  current: v1
  ref: lifecycle/windfall-lifecycle.yml
rate_limiting:
  limit: 5 requests/second
  exceeded_status: 429
  exceeded_error: rate_limit
  guidance: Back off and retry after a brief delay; docs show a ~0.2s inter-request delay for batch loops.
error_envelope:
  shape: '{ "error": "<type>", "message": "<human-readable>" }'
  format: custom-json (not RFC 9457)
  ref: errors/windfall-problem-types.yml
request:
  method: POST
  content_type: application/json
  correlation: >-
    Supply an `id` in the request body; it is echoed back on the response for
    correlation with your system of record.
response:
  match_flags:
  - household_matched
  - career_matched
  note: >-
    Always check household_matched and career_matched before accessing the nested
    household/career objects — each object is omitted when its flag is false.
  configurability: Returned household/career fields vary by account configuration.
request_constraints:
  max_emails: 10
  max_phones: 10
  max_addresses: 10
  exceeded_status: 400
  source: https://api-docs.windfall.com/sandbox/
  note: >-
    Each identifier array accepts at most 10 entries; exceeding any of the three
    returns a 400. This ceiling appears only in the Sandbox page's
    naturally-occurring-errors table — it is not in the OpenAPI schema, so a
    client generated from the spec will not enforce it.
matching:
  note: >-
    Matching is combination-based, not field-based. A request resolves when one
    matcher combination is satisfiable. Name alone never matches, and a partial
    address (street without zipcode) never matches. Adding extra non-matching
    fields is harmless.
  combinations:
  - {name: Email, required_fields: [emails]}
  - {name: Full address, required_fields: ['addresses[].address (number + street)', 'addresses[].zipcode']}
  - {name: Phone + name, required_fields: [phones, first_name, last_name]}
  source: https://api-docs.windfall.com/sandbox/
no_match_semantics:
  status: 200
  note: >-
    A no-match is a successful 200, not an error. Branch on household_matched /
    career_matched, never on the status code.
  ref: errors/windfall-problem-types.yml
testing:
  sandbox: https://api.windfalldata.com/sandbox/v1
  error_simulation_header: X-Windfall-Sandbox-Error
  error_simulation_values: ['400', '429', '500', '503']
  note: >-
    The sandbox is deterministic and non-billed, and ships a header-driven error
    simulator — the only way to exercise the 500 and 503 code paths.
  ref: sandbox/windfall-sandbox.yml
entitlement:
  note: >-
    Response field availability is contractual. Which household fields return
    depends on the customer's Windfall plan, and any career field requires
    Career Intelligence (CI) on the account. Treat every documented field as
    optional.
  ref: data-model/windfall-data-model.yml
coverage:
  geography: United States only
  freshness: Updated weekly