Enrich your first signup

This example starts with a signup email and ends with a company domain you can use in your account workflow. Run requests from your backend, with your API key stored in WATERFALL_API_KEY.

Replace the example email with a record you want to enrich. Requests use the live Waterfall API and your account’s configured rates. Viewing this local documentation makes no enrichment calls by itself.

curl --request POST 'https://api.waterfall.io/v1/enrichment/contact' \
  --header "x-api-key: $WATERFALL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "james.dev@example.com",
    "custom_fields": {
      "user_id": "usr_1042",
      "workspace_id": "ws_208",
      "source": "signup"
    }
  }'

The response contains job_id. Keep it with your signup record. custom_fields is returned with the result so you can connect it to the right user and workspace.

2. Retrieve the result

Replace YOUR_JOB_ID with the returned identifier:

curl --get 'https://api.waterfall.io/v1/enrichment/contact' \
  --header "x-api-key: $WATERFALL_API_KEY" \
  --data-urlencode 'job_id=YOUR_JOB_ID'

While the job is RUNNING, wait and poll again with backoff. Stop on a terminal state. On SUCCEEDED, inspect output.person; job completion does not guarantee a usable match. See results and delivery. A successful match can include these fields. This is a response excerpt, not a full response:

{
  "output": {
    "person": {
      "first_name": "James",
      "last_name": "Lee",
      "title": "Senior Platform Engineer",
      "company_name": "Northstar",
      "company_domain": "northstar.example",
      "location": "San Francisco, California, United States"
    }
  }
}

3. Enrich the company

If output.person.company_domain is available, pass it to Company Enrichment. Use the matched company domain, rather than the domain of a personal email provider.

curl --request POST 'https://api.waterfall.io/v1/enrichment/company' \
  --header "x-api-key: $WATERFALL_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "northstar.example",
    "custom_fields": {"workspace_id": "ws_208"}
  }'

This starts a separate job. Retrieve it with Get account results, or supply a webhook_url when launching.

4. Use it in your workflow

Join the returned profile and company data to your own usage events. Your application decides whether to tailor onboarding, review an account, or route it to sales.

Build signup qualification

Connect enrichment to account fit and product usage.

Receive results by webhook

Send completed enrichment to your backend.

Start here

Use cases

Signups & accounts

Find your buying team

Visitors & existing users

Monitoring

Integration essentials

2. Retrieve the result

3. Enrich the company

4. Use it in your workflow

Build signup qualification

Receive results by webhook

​1. Send the signup email

​2. Retrieve the result

​3. Enrich the company

​4. Use it in your workflow

Build signup qualification

Receive results by webhook

1. Send the signup email

2. Retrieve the result

3. Enrich the company

4. Use it in your workflow