Sandbox

Endpoint & authentication

Sandbox tokens are issued by Windfall and always begin with sandbox_. Contact your account representative to provision one; see Authentication for details. Production tokens do not work on the sandbox endpoint and sandbox tokens do not work on production — either combination returns 403.

curl -X POST https://api.windfalldata.com/sandbox/v1 \
  -H "Content-Type: application/json" \
  -H "X-WF-Auth-Token: sandbox_YOUR_KEY" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "addresses": [{"address": "100 Sandbox Ln", "zipcode": "80201"}]
  }'

Match scenarios

The sandbox supports four match outcomes. Send a request that includes a valid matching combination from one of the personas — see what constitutes a match for the field requirements — to deterministically trigger that scenario.

A few response rules apply across all scenarios:

• If the request includes an id, it is echoed back on the response.
• The household object is omitted when household_matched is false; the career object is omitted when career_matched is false.

curl -X POST https://api.windfalldata.com/sandbox/v1 \
  -H "Content-Type: application/json" \
  -H "X-WF-Auth-Token: sandbox_YOUR_KEY" \
  -d '{
    "first_name": "Amanda",
    "last_name": "Taylor",
    "addresses": [{"address": "100 Demo St", "zipcode": "30301"}],
    "emails": ["amanda.taylor@sandbox.windfall.com"],
    "phones": ["5553000001"]
  }'

{
  "household_matched": true,
  "career_matched": true,
  "household": { "net_worth": 1000000, /* ... */ },
  "career": { "job_title": "Software Engineer", /* ... */ }
}

{
  "household_matched": true,
  "career_matched": false,
  "household": { "net_worth": 1000000, /* ... */ }
}

{
  "household_matched": false,
  "career_matched": true,
  "career": { "job_title": "Software Engineer", /* ... */ }
}

{
  "household_matched": false,
  "career_matched": false
}

Persona reference

The sandbox includes 15 personas across 3 match categories — 5 example profiles in each. The profiles range from modest to ultra-high net worth (and individual contributor to CEO for career personas), giving you a representative sample of the response shapes production might return.

What constitutes a match

The sandbox uses the same matchers as production. A request matches a persona when one of Windfall's matchers can resolve against the fields in the request. Below are examples of some of those matchers:

Sending only first_name / last_name will not match. Sending only a partial address (e.g., street name without the zipcode) will not match. Adding extra non-matching fields is fine — once any combination above resolves, the match succeeds.

Household + career — full enrichment

Career enrichment is only returned for accounts with Career Intelligence (CI) enabled.

Household only — wealth & household enrichment

Career only — career & employment enrichment

Career enrichment is only returned for accounts with Career Intelligence (CI) enabled. Without CI, requests for these personas resolve as no match.

Every field that can appear in a production response is populated by at least one persona, so you can validate parsers and downstream logic against realistic data.

Error simulation

Test your error-handling code paths without needing to trigger the underlying conditions. Add the X-Windfall-Sandbox-Error header to any sandbox request and the API returns the requested status with body {"message": "..."}.

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: HTTP 429
# {"message": "Rate limit exceeded"}

Naturally-occurring errors

Beyond the simulator, the sandbox returns these errors under the same real conditions production does:

Error responses always have shape {"message": "..."}.