Results: polling or webhooks

For signup and company enrichment, choose how to receive the result: poll with the job_id, or provide webhook_url and let Waterfall send it to your backend or workflow tool when it’s ready.

Check how your endpoint returns results

Workflow	Delivery
Enrich signups	Asynchronous. Poll by `job_id` or supply `webhook_url`.
Enrich accounts	Asynchronous. Poll by `job_id` or supply `webhook_url`.
Find relevant people	Synchronous. Read `output.persons` in the response.
Discover account roles	Synchronous. Read `output.titles` in the response.
Identify visiting companies	Synchronous. Read the company and confidence in `output`.
Track users across companies	Synchronous. Read `output.job_change_status`.

Poll for enrichment results

Store the job_id returned by the POST request. Retrieve that job using the corresponding GET endpoint.

Status	What your application should do
`RUNNING`	Wait and poll again with backoff.
`SUCCEEDED`	Stop polling and inspect the available output.
`FAILED`	Stop polling and handle the failure.
`TIMED_OUT`	Stop polling and handle the timeout.
`ABORTED`	Stop polling and handle the aborted job.

Set a limit on how long your application polls. A 2, 4, then 8 second delay is one possible backoff policy, not an API response-time guarantee. Respect Retry-After when present. A completed job can have missing profile or company data. Treat missing fields as unknown when qualifying the account.

Receive a webhook instead

Add your backend’s or workflow tool’s webhook URL when starting an enrichment job:

{
  "email": "james.dev@example.com",
  "webhook_url": "https://your-app.example/webhooks/waterfall",
  "custom_fields": {
    "user_id": "usr_1042",
    "workspace_id": "ws_208"
  }
}

Waterfall delivers the result to your endpoint. Follow webhook verification and make your handler safe to process repeated deliveries. Match results to your records using the job ID and your own identifiers.

Write results to your stack

Your receiver or polling job can write the returned data into PostgreSQL, Snowflake, Clay, or your CRM. Use the destination’s API or connector in your workflow. A database connection string is not a webhook_url.

Start here

Use cases

Signups & accounts

Find your buying team

Visitors & existing users

Monitoring

Integration essentials

Check how your endpoint returns results

Poll for enrichment results

Receive a webhook instead

Write results to your stack

​Check how your endpoint returns results

​Poll for enrichment results

​Receive a webhook instead

​Write results to your stack

Check how your endpoint returns results

Poll for enrichment results

Receive a webhook instead

Write results to your stack