Job Change Launcher

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

Job Change Detection OverviewYou input: Previous company identifier (domain or LinkedIn) + contact identifier (LinkedIn, email, or name)You get: Job change status — moved, left, no_change, or unknown — and a profile snapshot when available

Job Change returns results synchronously — status and output are included directly in the response.

Supported input combinations

Provide as many fields as you have — more signals increase match accuracy.

Combination	Required fields	Notes
Domain + contact LinkedIn	`company_domain` + `contact_linkedin`	Highest coverage. Recommended.
Domain + professional email	`company_domain` + `professional_email`	—
Domain + personal email	`company_domain` + `personal_email`	—
Company LinkedIn + contact LinkedIn	`company_linkedin` + `contact_linkedin`	—
Company LinkedIn + professional email	`company_linkedin` + `professional_email`	—
Professional email only	`professional_email`	Minimum viable input.

company_domain + contact_linkedin yields the highest coverage. When possible, include both.

Business notes

Add your internal notes here — pricing, use cases, etc.

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": {}
}

Company Enrichment Finder

Job Change Finder

General guidance

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Support

Supported input combinations

Business notes

Authorizations

Body

Response

​Supported input combinations

​Business notes

Authorizations

Body

Response

Supported input combinations

Business notes