Enrich signups

Contact Enrichment Launcher

curl --request POST \
  --url https://api.waterfall.io/v1/enrichment/contact \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "james.dev@gmail.com",
  "custom_fields": {
    "crm_id": "crm_208",
    "record_id": "usr_1042",
    "tier": "free"
  }
}
'

import requests

url = "https://api.waterfall.io/v1/enrichment/contact"

payload = {
    "email": "james.dev@gmail.com",
    "custom_fields": {
        "crm_id": "crm_208",
        "record_id": "usr_1042",
        "tier": "free"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: 'james.dev@gmail.com',
    custom_fields: {crm_id: 'crm_208', record_id: 'usr_1042', tier: 'free'}
  })
};

fetch('https://api.waterfall.io/v1/enrichment/contact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/enrichment/contact",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'james.dev@gmail.com',
    'custom_fields' => [
        'crm_id' => 'crm_208',
        'record_id' => 'usr_1042',
        'tier' => 'free'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/enrichment/contact"

	payload := strings.NewReader("{\n  \"email\": \"james.dev@gmail.com\",\n  \"custom_fields\": {\n    \"crm_id\": \"crm_208\",\n    \"record_id\": \"usr_1042\",\n    \"tier\": \"free\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.waterfall.io/v1/enrichment/contact")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"james.dev@gmail.com\",\n  \"custom_fields\": {\n    \"crm_id\": \"crm_208\",\n    \"record_id\": \"usr_1042\",\n    \"tier\": \"free\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/enrichment/contact")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"james.dev@gmail.com\",\n  \"custom_fields\": {\n    \"crm_id\": \"crm_208\",\n    \"record_id\": \"usr_1042\",\n    \"tier\": \"free\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "dae884ce-50aa-g208-b24f-f30687a00368",
  "start_date": "2021-06-04T18:21:49.665000+00:00"
}

POST

enrichment

contact

Contact Enrichment Launcher

curl --request POST \
  --url https://api.waterfall.io/v1/enrichment/contact \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "james.dev@gmail.com",
  "custom_fields": {
    "crm_id": "crm_208",
    "record_id": "usr_1042",
    "tier": "free"
  }
}
'

import requests

url = "https://api.waterfall.io/v1/enrichment/contact"

payload = {
    "email": "james.dev@gmail.com",
    "custom_fields": {
        "crm_id": "crm_208",
        "record_id": "usr_1042",
        "tier": "free"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: 'james.dev@gmail.com',
    custom_fields: {crm_id: 'crm_208', record_id: 'usr_1042', tier: 'free'}
  })
};

fetch('https://api.waterfall.io/v1/enrichment/contact', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v1/enrichment/contact",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'james.dev@gmail.com',
    'custom_fields' => [
        'crm_id' => 'crm_208',
        'record_id' => 'usr_1042',
        'tier' => 'free'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v1/enrichment/contact"

	payload := strings.NewReader("{\n  \"email\": \"james.dev@gmail.com\",\n  \"custom_fields\": {\n    \"crm_id\": \"crm_208\",\n    \"record_id\": \"usr_1042\",\n    \"tier\": \"free\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.waterfall.io/v1/enrichment/contact")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"james.dev@gmail.com\",\n  \"custom_fields\": {\n    \"crm_id\": \"crm_208\",\n    \"record_id\": \"usr_1042\",\n    \"tier\": \"free\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v1/enrichment/contact")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"james.dev@gmail.com\",\n  \"custom_fields\": {\n    \"crm_id\": \"crm_208\",\n    \"record_id\": \"usr_1042\",\n    \"tier\": \"free\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "dae884ce-50aa-g208-b24f-f30687a00368",
  "start_date": "2021-06-04T18:21:49.665000+00:00"
}

This request starts an enrichment job. It returns a job_id, not the finished profile.Save that ID, then use Get signup results to check progress and retrieve the profile. Or add webhook_url and we’ll send the result to your endpoint when it’s ready.

Send a personal or work email to look up the person’s role, current company, location, and work history when available.

{
  "email": "james.dev@gmail.com",
  "custom_fields": {
    "crm_id": "crm_208",
    "record_id": "usr_1042",
    "tier": "free"
  }
}

Using a workflow tool? Add its webhook URL as webhook_url in this request. We’ll send the completed result there, so you don’t need to poll. See an example. Use custom_fields for your CRM ID, record ID, or plan tier. These values come back unchanged with the result, so you can connect it to the right record. They do not affect matching or score the signup.

Pick the identifier you have

Input	Fields
Personal or work email	`email`
LinkedIn profile	`linkedin`
Name and company domain	`full_name` + `domain`
Separate first and last names	`first_name` + `last_name` + `domain`

Waterfall uses the highest-priority input you provide: email first, then LinkedIn, then name and domain. If that lookup fails, it does not fall back to the other inputs.

Receive the result in your backend

To retrieve the result yourself, call:

GET /v1/enrichment/contact?job_id=YOUR_JOB_ID

While the job is RUNNING, wait and check again with backoff. When it is SUCCEEDED, read output.person. Stop polling if it fails, times out, or is aborted. See Get signup results for the full request and polling or webhooks for delivery details. Run enrichment separately so signup doesn’t have to wait. Phone enrichment is optional and can add charges. Leave it off when your workflow only needs person and company context. Next: Enrich the account using the matched company domain, or follow the signup qualification guide.

Authorizations

x-api-key

string

header

required

To access the API, provide your API key in x-api-key.

Body

application/json

Contact enrichment payload: provide one identifier strategy (linkedin, email, full_name + domain, or first_name + last_name + domain) plus optional include_phones, webhook_url, and custom_fields.

Option 1
Option 2
Option 3
Option 4

Request payload to launch a contact enrichment job.

string | null

required

Company LinkedIn URL or ID/handle (for example google from https://www.linkedin.com/company/google/). Recommended input to maximize coverage.

Required string length: 3 - 500

Example:

"waterfall-io"

full_name

string | null

Full name of the contact. Providing first_name and last_name is preferable when both are available.

Required string length: 4 - 250

Example:

"John Doe"

first_name

string | null

First name of the contact.

Required string length: 1 - 100

Example:

"John"

last_name

string | null

Last name of the contact.

Required string length: 1 - 100

Example:

"Doe"

domain

string

The domain where you want to find contacts. It can be a plain domain or a full URL; Waterfall automatically extracts the company domain.

Required string length: 4 - 500

Example:

"waterfall.io"

string<email>

Professional or personal email address.

Required string length: 6 - 254

Example:

"john.doe@example.com"

include_phones

boolean

default:false

Default false. If set to true, Waterfall runs advanced phone enrichment to maximize phone coverage and additional charges may apply when numbers are found.

webhook_url

string<uri>

Optional webhook callback URL. If supplied, Waterfall POSTs the same payload returned by the Finder endpoint when processing completes. If your webhook responds with 429, 500, 502, or 504, Waterfall retries delivery up to 5 times with exponential backoff. Waterfall includes X-Webhook-Signature containing a compact JWT when webhook signing configuration is available. The JWT protected header contains alg: "EdDSA", kid, and typ: "JWT". Its claims contain iat, exp, jti, job_id, body_hash, and body_hash_alg: "sha-256". body_hash is the unpadded base64url-encoded SHA-256 digest of the exact raw request body bytes. The JSON body is unchanged by signing. Signatures expire exactly 15 minutes after iat; receivers should reject expired signatures. If signing configuration is unavailable or invalid, Waterfall preserves backward compatibility by sending the callback unsigned without X-Webhook-Signature.

Maximum string length: 2083

Example:

"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1"

custom_fields

object | null

Optional custom key-value metadata echoed on job input and output (useful for correlating internal source metadata). On create requests, omit the field or send JSON null when no custom fields are needed; both are stored as {}. When present, the value must be a JSON object with keys matching ^[A-Za-z0-9_-]+$ and values that are a string (max 1000 characters), number, or boolean. Empty string, arrays, and other non-object types return HTTP 400. On job GET responses, input.task.custom_fields is always an object ({} or populated).

Example:

{
  "tenantId": "0e9d26b7-cdb5-4d95-b248-59ac389d2e8a",
  "workflowId": "ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4",
  "waterfallRequestId": "1b49c542-f47a-406b-a95f-a1859d1461af"
}

Response

Contact enrichment job successfully launched.

Response returned when a contact enrichment job is successfully launched.

job_id

string<uuid>

required

A UUID.

Example:

"7d44db58-5de3-4e92-a2fb-8325d12c2e8b"

start_date

string<date-time>

required

A date time in ISO 8601 format.

Example:

"2025-02-05T15:46:35.771751+00:00"

Start here

Use cases

Signups & accounts

Find your buying team

Visitors & existing users

Monitoring

Integration essentials

Pick the identifier you have

Receive the result in your backend

Authorizations

Body

Response

​Send your signup context

​Pick the identifier you have

​Receive the result in your backend

Authorizations

Body

Response

Send your signup context

Pick the identifier you have

Receive the result in your backend