Track users across companies

curl --request POST \
  --url https://api.waterfall.io/v1/job/change \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "company_domain": "scale.com",
  "contact_linkedin": "connor-heggie"
}
'

{
  "status": "SUCCEEDED",
  "start_date": "2025-03-28T22:44:23.566762+00:00",
  "stop_date": "2025-03-28T22:44:24.052251+00:00",
  "input": {
    "task": {
      "company_domain": "digitalriver.com",
      "professional_email": "jane.doe@digitalriver.com",
      "custom_fields": {},
      "job_id": "db1390dd-f2fa-4cb4-a77a-e651e785d12c",
      "context_id": "db1390dd-f2fa-4cb4-a77a-e651e785d12c"
    }
  },
  "output": {
    "job_change_status": "moved",
    "person": {
      "id": "e70fc5a3-55d9-43e5-93ea-b9e8210435da",
      "first_name": "Jane",
      "last_name": "Doe",
      "linkedin_id": "jane-doe-abc123",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe-abc123/",
      "about": "Sales professional with a background in SaaS and enterprise software.",
      "location": "San Francisco, California, United States",
      "country": "United States",
      "company_linkedin_id": "acme-corp",
      "company_name": "Acme Corp",
      "company_domain": "acme.com",
      "title": "Head of Sales",
      "seniority": "Director",
      "department": "Sales",
      "experiences": [
        {
          "title": "Head of Sales",
          "location": "San Francisco, CA",
          "company_name": "Acme Corp",
          "company_linkedin_id": "acme-corp",
          "company_linkedin_url": "https://www.linkedin.com/company/acme-corp/",
          "company_domain": "acme.com",
          "start_year": 2023,
          "start_month": 11,
          "start_date": "2023-11-01",
          "is_current": true
        },
        {
          "title": "Senior Account Executive",
          "location": "Remote",
          "company_name": "Digital River",
          "company_linkedin_id": "digital-river",
          "company_linkedin_url": "https://www.linkedin.com/company/digital-river/",
          "company_domain": "digitalriver.com",
          "start_year": 2019,
          "start_month": 7,
          "start_date": "2019-07-01",
          "end_year": 2023,
          "end_month": 10,
          "end_date": "2023-10-01",
          "is_current": false
        }
      ]
    },
    "usage": {
      "total_usd": 0.05,
      "balance_remaining_usd": 99.95,
      "persons_count": 1,
      "persons_usd": 0.05,
      "phones_count": 0,
      "phones_usd": 0,
      "companies_count": 0,
      "companies_usd": 0
    }
  }
}

POST

job

change

curl --request POST \
  --url https://api.waterfall.io/v1/job/change \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "company_domain": "scale.com",
  "contact_linkedin": "connor-heggie"
}
'

{
  "status": "SUCCEEDED",
  "start_date": "2025-03-28T22:44:23.566762+00:00",
  "stop_date": "2025-03-28T22:44:24.052251+00:00",
  "input": {
    "task": {
      "company_domain": "digitalriver.com",
      "professional_email": "jane.doe@digitalriver.com",
      "custom_fields": {},
      "job_id": "db1390dd-f2fa-4cb4-a77a-e651e785d12c",
      "context_id": "db1390dd-f2fa-4cb4-a77a-e651e785d12c"
    }
  },
  "output": {
    "job_change_status": "moved",
    "person": {
      "id": "e70fc5a3-55d9-43e5-93ea-b9e8210435da",
      "first_name": "Jane",
      "last_name": "Doe",
      "linkedin_id": "jane-doe-abc123",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe-abc123/",
      "about": "Sales professional with a background in SaaS and enterprise software.",
      "location": "San Francisco, California, United States",
      "country": "United States",
      "company_linkedin_id": "acme-corp",
      "company_name": "Acme Corp",
      "company_domain": "acme.com",
      "title": "Head of Sales",
      "seniority": "Director",
      "department": "Sales",
      "experiences": [
        {
          "title": "Head of Sales",
          "location": "San Francisco, CA",
          "company_name": "Acme Corp",
          "company_linkedin_id": "acme-corp",
          "company_linkedin_url": "https://www.linkedin.com/company/acme-corp/",
          "company_domain": "acme.com",
          "start_year": 2023,
          "start_month": 11,
          "start_date": "2023-11-01",
          "is_current": true
        },
        {
          "title": "Senior Account Executive",
          "location": "Remote",
          "company_name": "Digital River",
          "company_linkedin_id": "digital-river",
          "company_linkedin_url": "https://www.linkedin.com/company/digital-river/",
          "company_domain": "digitalriver.com",
          "start_year": 2019,
          "start_month": 7,
          "start_date": "2019-07-01",
          "end_year": 2023,
          "end_month": 10,
          "end_date": "2023-10-01",
          "is_current": false
        }
      ]
    },
    "usage": {
      "total_usd": 0.05,
      "balance_remaining_usd": 99.95,
      "persons_count": 1,
      "persons_usd": 0.05,
      "phones_count": 0,
      "phones_usd": 0,
      "companies_count": 0,
      "companies_usd": 0
    }
  }
}

Check whether a customer still works at the company you have on file. If they’ve moved, you can review their new company and decide whether to reconnect.

Only pay when a job change is found. You aren’t charged for unchanged or inconclusive results. Company enrichment after the check is billed separately.

This endpoint performs one check and returns the result synchronously. Schedule repeat checks in your own workflow; calling it does not create an ongoing monitor.

{
  "company_domain": "northstar.example",
  "contact_linkedin": "https://www.linkedin.com/in/james-lee-example",
  "custom_fields": {
    "user_id": "usr_1042",
    "account_id": "acct_208",
    "source": "customer-refresh"
  }
}

For best results, send the company domain and the contact’s LinkedIn profile. The endpoint also supports email and other identifier combinations shown in the schema below.

Decide what to do with the result

Read output.job_change_status:

Result	Next step in your workflow
`moved`	Review the returned profile for the new company and role.
`left`	Flag that the person has left; a new company may not be known.
`no_change`	Keep the current company association.
`unknown`	Keep the existing record and treat the check as inconclusive.

output.person contains a profile snapshot when available and can be empty. Contact channels are redacted. Check the returned fields before updating your CRM. Next: Follow a customer to a new company. For a prior result, use the job retrieval reference.

Authorizations

x-api-key

string

header

required

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

Body

application/json

Job Change request payload with company/person identifiers and optional custom_fields.

Request payload for Job Change. Valid input sets include: 1) company_domain + (contact_linkedin, professional_email, personal_email, or contact_full_name) 2) company_linkedin + (contact_linkedin, professional_email, or personal_email) 3) professional_email (optionally with contact_full_name)

company_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"

contact_linkedin

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"

company_linkedin

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"

professional_email

string<email> | null

Professional or personal email address.

Required string length: 6 - 254

Example:

"john.doe@waterfall.io"

personal_email

string<email> | null

Professional or personal email address.

Required string length: 6 - 254

Example:

"john.doe@gmail.com"

contact_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"

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

Job Change result returned successfully.

Job Change response with job state, input, and optional output.

status

enum<string>

required

The status of the job.

Available options:

RUNNING,

SUCCEEDED,

FAILED,

TIMED_OUT,

ABORTED

Example:

"RUNNING"

start_date

string<date-time>

required

A date time in ISO 8601 format.

Example:

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

input

object | null

required

Show child attributes

Example:

{
  "task": {
    "company_domain": "scale.com",
    "company_linkedin": null,
    "professional_email": null,
    "personal_email": null,
    "contact_linkedin": null,
    "contact_full_name": "Connor Heggie",
    "custom_fields": {},
    "job_id": "56d6add5-0bdd-4834-9b9b-390c08df31e9",
    "context_id": "56d6add5-0bdd-4834-9b9b-390c08df31e9"
  }
}

stop_date

string<date-time>

A date time in ISO 8601 format.

Example:

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

output

object

Job Change output payload.

Show child attributes

Example:

{
  "job_change_status": "unknown",
  "person": {}
}

Start here

Use cases

Signups & accounts

Find your buying team

Visitors & existing users

Monitoring

Integration essentials

Decide what to do with the result

Authorizations

Body

Response

​Decide what to do with the result

Authorizations

Body

Response

Decide what to do with the result