> ## Documentation Index
> Fetch the complete documentation index at: https://devtools.waterfall.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich your first signup

> Send an email, retrieve the profile, and pass the company domain into account enrichment.

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`.

<Note>
  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.
</Note>

## 1. Send the signup email

```bash theme={null}
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:

```bash theme={null}
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](/v1/results).

A successful match can include these fields. This is a **response excerpt**, not a full response:

```json theme={null}
{
  "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.

```bash theme={null}
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](/v1/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.

<CardGroup cols={2}>
  <Card title="Build signup qualification" icon="filter" href="/v1/qualify-signups">Connect enrichment to account fit and product usage.</Card>
  <Card title="Receive results by webhook" icon="bolt" href="/v1/results">Send completed enrichment to your backend.</Card>
</CardGroup>