Quickstart
Make your first API request in under a minute.
Prerequisites
- An API token from Windfall (see Authentication)
- cURL, Python, or Node.js installed
Step 1: Make Your First Request
Send a POST request with a person record to the Windfall API. Replace YOUR_API_TOKEN with your actual token.
# Enrich a person record curl -X POST https://api.windfalldata.com/v1/ \ -H "Content-Type: application/json" \ -H "X-WF-Auth-Token: YOUR_API_TOKEN" \ -d '{ "id": "16a903p", "first_name": "Jane", "last_name": "Doe", "addresses": [ { "address": "123 Main St Apt A", "city": "San Francisco", "state": "CA", "zipcode": "94133" } ], "emails": ["jdoe@windfall.com"], "phones": ["415-555-1212"] }'import requests response = requests.post( "https://api.windfalldata.com/v1/", headers={ "Content-Type": "application/json", "X-WF-Auth-Token": "YOUR_API_TOKEN", }, json={ "id": "16a903p", "first_name": "Jane", "last_name": "Doe", "addresses": [{ "address": "123 Main St Apt A", "city": "San Francisco", "state": "CA", "zipcode": "94133", }], "emails": ["jdoe@windfall.com"], "phones": ["415-555-1212"], }, ) print(response.json())const response = await fetch( "https://api.windfalldata.com/v1/", { method: "POST", headers: { "Content-Type": "application/json", "X-WF-Auth-Token": "YOUR_API_TOKEN", }, body: JSON.stringify({ id: "16a903p", first_name: "Jane", last_name: "Doe", addresses: [{ address: "123 Main St Apt A", city: "San Francisco", state: "CA", zipcode: "94133", }], emails: ["jdoe@windfall.com"], phones: ["415-555-1212"], }), } ); const data = await response.json(); console.log(data);
Step 2: Examine the Response
A successful match returns enriched household and career data.
Response
{
"id": "16a903p",
"household": {
"confidence": 1.0,
"windfall_id": "bde3d183ad6215f2932217ee5d6d368a",
"net_worth": 4200000,
"boat_owner": false,
"plane_owner": false,
"multi_property_owner": true,
"philanthropic_giver": true,
"political_donor": false,
"small_business_owner": false
},
"career": {
"confidence": 0.7,
"linkedin_url": "linkedin.com/in/jane-doe-san-francisco",
"job_title": "VP of Marketing",
"company_name": "Acme Inc",
"recently_changed_jobs": false
},
"household_matched": true,
"career_matched": true
}household
Contains wealth and lifestyle data for the matched household.
career
Contains employment and professional data for the individual.
confidence
Ranges from 0 to 1 — higher means a stronger match.
household_matched / career_matched
Indicate whether data was found for each category.
Step 3: Handle a No-Match Response
When no match is found, the response returns null for the data objects.
No-Match Response
{
"id": "16a903p",
"household": null,
"career": null,
"household_matched": false,
"career_matched": false
}Check household_matched and career_matched before accessing nested fields to avoid null reference errors.