Enrich accounts

Company Enrichment Launcher

curl --request POST \
  --url https://api.waterfall.io/v1/enrichment/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "domain": "waterfall.io",
  "linkedin": "waterfall-io",
  "name": "Waterfall",
  "webhook_url": "https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1",
  "custom_fields": {
    "tenantId": "0e9d26b7-cdb5-4d95-b248-59ac389d2e8a",
    "workflowId": "ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4",
    "waterfallRequestId": "1b49c542-f47a-406b-a95f-a1859d1461af"
  }
}
'

import requests

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

payload = {
    "domain": "waterfall.io",
    "linkedin": "waterfall-io",
    "name": "Waterfall",
    "webhook_url": "https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1",
    "custom_fields": {
        "tenantId": "0e9d26b7-cdb5-4d95-b248-59ac389d2e8a",
        "workflowId": "ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4",
        "waterfallRequestId": "1b49c542-f47a-406b-a95f-a1859d1461af"
    }
}
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({
    domain: 'waterfall.io',
    linkedin: 'waterfall-io',
    name: 'Waterfall',
    webhook_url: 'https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1',
    custom_fields: {
      tenantId: '0e9d26b7-cdb5-4d95-b248-59ac389d2e8a',
      workflowId: 'ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4',
      waterfallRequestId: '1b49c542-f47a-406b-a95f-a1859d1461af'
    }
  })
};

fetch('https://api.waterfall.io/v1/enrichment/company', 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/company",
  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([
    'domain' => 'waterfall.io',
    'linkedin' => 'waterfall-io',
    'name' => 'Waterfall',
    'webhook_url' => 'https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1',
    'custom_fields' => [
        'tenantId' => '0e9d26b7-cdb5-4d95-b248-59ac389d2e8a',
        'workflowId' => 'ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4',
        'waterfallRequestId' => '1b49c542-f47a-406b-a95f-a1859d1461af'
    ]
  ]),
  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/company"

	payload := strings.NewReader("{\n  \"domain\": \"waterfall.io\",\n  \"linkedin\": \"waterfall-io\",\n  \"name\": \"Waterfall\",\n  \"webhook_url\": \"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1\",\n  \"custom_fields\": {\n    \"tenantId\": \"0e9d26b7-cdb5-4d95-b248-59ac389d2e8a\",\n    \"workflowId\": \"ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4\",\n    \"waterfallRequestId\": \"1b49c542-f47a-406b-a95f-a1859d1461af\"\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/company")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"domain\": \"waterfall.io\",\n  \"linkedin\": \"waterfall-io\",\n  \"name\": \"Waterfall\",\n  \"webhook_url\": \"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1\",\n  \"custom_fields\": {\n    \"tenantId\": \"0e9d26b7-cdb5-4d95-b248-59ac389d2e8a\",\n    \"workflowId\": \"ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4\",\n    \"waterfallRequestId\": \"1b49c542-f47a-406b-a95f-a1859d1461af\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"domain\": \"waterfall.io\",\n  \"linkedin\": \"waterfall-io\",\n  \"name\": \"Waterfall\",\n  \"webhook_url\": \"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1\",\n  \"custom_fields\": {\n    \"tenantId\": \"0e9d26b7-cdb5-4d95-b248-59ac389d2e8a\",\n    \"workflowId\": \"ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4\",\n    \"waterfallRequestId\": \"1b49c542-f47a-406b-a95f-a1859d1461af\"\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

company

Company Enrichment Launcher

curl --request POST \
  --url https://api.waterfall.io/v1/enrichment/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "domain": "waterfall.io",
  "linkedin": "waterfall-io",
  "name": "Waterfall",
  "webhook_url": "https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1",
  "custom_fields": {
    "tenantId": "0e9d26b7-cdb5-4d95-b248-59ac389d2e8a",
    "workflowId": "ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4",
    "waterfallRequestId": "1b49c542-f47a-406b-a95f-a1859d1461af"
  }
}
'

import requests

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

payload = {
    "domain": "waterfall.io",
    "linkedin": "waterfall-io",
    "name": "Waterfall",
    "webhook_url": "https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1",
    "custom_fields": {
        "tenantId": "0e9d26b7-cdb5-4d95-b248-59ac389d2e8a",
        "workflowId": "ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4",
        "waterfallRequestId": "1b49c542-f47a-406b-a95f-a1859d1461af"
    }
}
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({
    domain: 'waterfall.io',
    linkedin: 'waterfall-io',
    name: 'Waterfall',
    webhook_url: 'https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1',
    custom_fields: {
      tenantId: '0e9d26b7-cdb5-4d95-b248-59ac389d2e8a',
      workflowId: 'ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4',
      waterfallRequestId: '1b49c542-f47a-406b-a95f-a1859d1461af'
    }
  })
};

fetch('https://api.waterfall.io/v1/enrichment/company', 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/company",
  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([
    'domain' => 'waterfall.io',
    'linkedin' => 'waterfall-io',
    'name' => 'Waterfall',
    'webhook_url' => 'https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1',
    'custom_fields' => [
        'tenantId' => '0e9d26b7-cdb5-4d95-b248-59ac389d2e8a',
        'workflowId' => 'ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4',
        'waterfallRequestId' => '1b49c542-f47a-406b-a95f-a1859d1461af'
    ]
  ]),
  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/company"

	payload := strings.NewReader("{\n  \"domain\": \"waterfall.io\",\n  \"linkedin\": \"waterfall-io\",\n  \"name\": \"Waterfall\",\n  \"webhook_url\": \"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1\",\n  \"custom_fields\": {\n    \"tenantId\": \"0e9d26b7-cdb5-4d95-b248-59ac389d2e8a\",\n    \"workflowId\": \"ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4\",\n    \"waterfallRequestId\": \"1b49c542-f47a-406b-a95f-a1859d1461af\"\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/company")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"domain\": \"waterfall.io\",\n  \"linkedin\": \"waterfall-io\",\n  \"name\": \"Waterfall\",\n  \"webhook_url\": \"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1\",\n  \"custom_fields\": {\n    \"tenantId\": \"0e9d26b7-cdb5-4d95-b248-59ac389d2e8a\",\n    \"workflowId\": \"ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4\",\n    \"waterfallRequestId\": \"1b49c542-f47a-406b-a95f-a1859d1461af\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"domain\": \"waterfall.io\",\n  \"linkedin\": \"waterfall-io\",\n  \"name\": \"Waterfall\",\n  \"webhook_url\": \"https://webhook.site/70dd34e3-564d-4339-81e3-ed97416140a1\",\n  \"custom_fields\": {\n    \"tenantId\": \"0e9d26b7-cdb5-4d95-b248-59ac389d2e8a\",\n    \"workflowId\": \"ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4\",\n    \"waterfallRequestId\": \"1b49c542-f47a-406b-a95f-a1859d1461af\"\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"
}

Once you know the company domain, enrich the account. Combine the company details with your product usage data to decide whether the account fits your market.

Input: company domain, LinkedIn identifier, or company name.Output: a job_id. Retrieve output.company through Get account results or a webhook.

{
  "domain": "northstar.example",
  "custom_fields": {
    "workspace_id": "ws_208",
    "source": "signup-account"
  }
}

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 company data to assess fit

Data	Example use
Company size and industry	Apply your target-account criteria.
Location	Route to the relevant region.
`technologies`	Look for relevant technologies in the available company data.
`funding_details`	Add available funding totals and round history.
Company domain and LinkedIn	Connect the account to your existing records.

Technology and funding fields may be missing or empty. The endpoint returns the company data available. It does not run a live technology scan or calculate an account score.

Prefer domain or linkedin over company name alone. Name-only matching can select the wrong company. When several identifiers are sent, priority is domain, LinkedIn, then name. Next: Find relevant people at a qualified account, or combine account data with product usage.

Authorizations

x-api-key

string

header

required

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

Body

application/json

Company enrichment payload: provide one company identifier (domain, linkedin, or name) plus optional webhook_url and custom_fields.

Option 1
Option 2
Option 3

Request payload to launch a company enrichment job.

domain

string

required

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 | null

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"

name

string

The name of the company where you want to find contacts.

Required string length: 3 - 500

Example:

"Waterfall"

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

Company enrichment job successfully launched.

Response returned when a company 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

Use company data to assess fit

Authorizations

Body

Response

​Use company data to assess fit

Authorizations

Body

Response

Use company data to assess fit