Examples & FAQs

Common integration patterns and frequently asked questions.

Example 1: Minimal Request (Name Only)

cURL

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

Match rates improve significantly when you include address, email, or phone in addition to name.

Example 2: Handling Partial Matches

Sometimes the API matches a household but not a career record. In this case, household_matched is true while career_matched is false and the career object is null.

JSON Response

{
  "household_matched": true,
  "career_matched": false,
  "household": {
    "net_worth": 2500000,
    "confidence": 0.92
  },
  "career": null
}

Always check both flags before accessing nested data:

Python

data = response.json()
if data["household_matched"]:
    print(f"Net worth: {data['household']['net_worth']}")
if data["career_matched"]:
    print(f"Job title: {data['career']['job_title']}")

Example 3: Rate-Limit-Aware Batch Processing

This example reads a list of records and calls the API with a 0.2-second delay between requests to stay under the 5 req/s rate limit. It includes basic error handling for 429 responses with retry.

Python

import requests
import time

API_URL = "https://api.windfalldata.com/v1/"
HEADERS = {
    "Content-Type": "application/json",
    "X-WF-Auth-Token": "YOUR_API_TOKEN",
}

records = [
    {"id": "1", "first_name": "Jane", "last_name": "Doe", "emails": ["jdoe@example.com"]},
    {"id": "2", "first_name": "John", "last_name": "Smith", "phones": ["555-123-4567"]},
    # ... more records
]

results = []
for record in records:
    response = requests.post(API_URL, json=record, headers=HEADERS)

    if response.status_code == 429:
        time.sleep(1)  # Back off on rate limit
        response = requests.post(API_URL, json=record, headers=HEADERS)

    results.append(response.json())
    time.sleep(0.2)  # Stay under 5 req/s

Example 4: Error Handling

Proper error handling for common HTTP status codes in Node.js:

JavaScript

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",
  }),
});

if (response.ok) {
  const data = await response.json();
  console.log(data);
} else if (response.status === 429) {
  // Rate limited — wait and retry
  await new Promise(r => setTimeout(r, 1000));
  // ... retry request
} else if (response.status === 401) {
  console.error("Invalid API token");
} else {
  console.error(`Error: ${response.status}`);
}

Frequently Asked Questions

What PII fields are required?

No single field is strictly required, but providing a name plus at least one of address, email, or phone is recommended for reliable matches.

What does the confidence score mean?

The confidence score ranges from 0 to 1 and indicates how certain Windfall is about the match. A score of 1.0 means a very strong match; lower scores indicate less certainty. Both household and career objects include their own confidence scores.

How do I increase my rate limit or token quota?

Contact your Windfall account representative to discuss adjusting your plan.

Can I call the API from the browser?

No. Your API token should never be exposed in client-side code. Always call the API from a backend server.

What happens when my token quota is exhausted?

You will receive an error response. Contact Windfall to refresh or increase your quota.

Does the API support batch requests?

The API processes one record per request. For batch processing, send sequential requests with a brief delay between each to stay within rate limits. See the batch processing example above.

How often is Windfall's data updated?

Windfall updates its data on a weekly basis.