generated: '2026-08-14'
method: searched
source: https://api-docs.windfall.com/sandbox/
docs: https://api-docs.windfall.com/sandbox/
docs_last_updated: '2026-04'
verified: '2026-08-14'
description: >-
  Windfall publishes a non-billed sandbox that mirrors the production endpoint and
  returns deterministic responses from a fixed set of fictitious personas. It uses
  the identical request body, response shape, and matching pipeline as production —
  only the data source differs — so integrations can be built and tested without
  consuming credits or touching real customer data.
endpoint:
  base_url: https://api.windfalldata.com/sandbox/v1
  method: POST
  content_type: application/json
  auth_header: X-WF-Auth-Token
  rate_limit: 5 requests/second
  billing: non-billed (free; does not draw from token quota)
tokens:
  format: sandbox_YOUR_KEY
  prefix: sandbox_
  issuance: Issued by Windfall; contact your account representative to provision one.
  isolation: >-
    Production tokens do not work on the sandbox endpoint and sandbox tokens do not
    work on production; either mismatch returns 403.
match_scenarios:
- id: household_and_career
  description: Full enrichment — wealth, household, and career/employment data.
  personas: [Amanda Taylor, Daniel Garcia, Michelle Robinson, James Thompson, Catherine White]
- id: household_only
  description: Wealth and household data; career field absent.
  personas: [Jane Doe, Robert Smith, Sarah Johnson, Michael Williams, Elizabeth Brown]
- id: career_only
  description: Career/employment data only; household field absent. Requires Career Intelligence (CI) on the account.
  personas: [David Wilson, Jennifer Davis, Thomas Anderson, Patricia Martinez, Christopher Lee]
- id: no_match
  description: Any request that does not match a persona; both flags false, enrichment objects absent.
  personas: []
matchers:
  note: >-
    The sandbox uses the same matchers as production. A request matches a persona
    when one matcher combination resolves. Sending only first/last name will not match.
  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]
persona_notes:
  count: 15
  categories: 3
  per_category: 5
  ci_dependency: >-
    If the account does not have Career Intelligence (CI) enabled, the "Both" personas
    return household_matched true / career_matched false, and the "Career-only" personas
    return both flags false (no match).
example_request:
  first_name: Amanda
  last_name: Taylor
  addresses:
  - address: 100 Demo St
    zipcode: '30301'
  emails: [amanda.taylor@sandbox.windfall.com]
  phones: ['5553000001']
error_simulation:
  supported: true
  header: X-Windfall-Sandbox-Error
  description: >-
    Windfall ships a deterministic error simulator on the sandbox endpoint. Add
    the X-Windfall-Sandbox-Error header to any sandbox request and the API
    returns the requested status with body {"message": "..."} — letting a client
    exercise its error-handling code paths without having to trigger the
    underlying condition. This is the only way to test the 500 and 503 paths,
    which the docs describe as rare in the sandbox.
  source: https://api-docs.windfall.com/sandbox/
  values:
  - {value: '400', status: 400, meaning: Simulated invalid input}
  - {value: '429', status: 429, meaning: Simulated rate limit exceeded}
  - {value: '500', status: 500, meaning: Simulated unhandled error}
  - {value: '503', status: 503, meaning: Simulated downstream service unavailable}
  example:
    request: |
      curl -X POST https://api.windfalldata.com/sandbox/v1 \
        -H "Content-Type: application/json" \
        -H "X-WF-Auth-Token: sandbox_YOUR_KEY" \
        -H "X-Windfall-Sandbox-Error: 429" \
        -d '{"first_name": "Jane", "last_name": "Doe"}'
    response_status: 429
    response_body: '{"message": "Rate limit exceeded"}'
naturally_occurring_errors:
  note: >-
    Beyond the simulator, the sandbox returns these errors under the same real
    conditions production does. Error responses always have shape
    {"message": "..."}.
  ref: errors/windfall-problem-types.yml
  errors:
  - {status: 400, condition: 'Malformed request body or headers, or more than 10 emails / phones / addresses.'}
  - {status: 401, condition: Missing or invalid X-WF-Auth-Token.}
  - {status: 403, condition: Sandbox token used on production endpoint, or production token used on sandbox.}
  - {status: 429, condition: Rate limit exceeded (5 req/sec).}
  - {status: 500, condition: Unhandled server error. Rare in the sandbox — use the simulator to test this path.}
  - {status: 503, condition: Downstream service unavailable. Rare in the sandbox — use the simulator to test this path.}