Create a job changes watcher agent

curl --request POST \
  --url https://api.tryfuse.ai/api/v1/business/agents/job-changes-watcher \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "listName": "<string>"
}
'

import requests

url = "https://api.tryfuse.ai/api/v1/business/agents/job-changes-watcher"

payload = { "listName": "<string>" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({listName: '<string>'})
};

fetch('https://api.tryfuse.ai/api/v1/business/agents/job-changes-watcher', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "agent": {
    "id": "6a8dce4e65fd738c00d89289",
    "type": "job-changes-watcher",
    "name": "Customer job changes",
    "status": "initializing",
    "started": false
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

Agents

Create a job changes watcher agent

Creates a Job-changes watcher (from a list) agent (job-changes-watcher). Watches the PEOPLE of an existing list (exactly one of listId/listIds) for a new employer, a promotion or a new title, re-checking each watched contact every frequency days (monthly by default). Each watched contact costs 50 credits per check, with no setup fee and free deliveries. The first check only records each person’s current job, so a move made before they were watched is never delivered, and the first charge comes one check after the start. With start: false (the default) a DRAFT is saved — status initializing, nothing billed: read it back with GET /business/agents/, adjust it with PATCH /business/agents/, then start it with POST /business/agents//activate. With start: true the agent is created AND started in one call: its dedicated results list is created, the balance is checked against one check of every watched contact, and the provider subscriptions are set up. Either way the answer is 201 { agent: { id, type, name, status, started } } — the same shape for every agent kind, draft or started. Poll GET /business/agents for status and contactsFound, and read the delivered rows with the Lists endpoints via the agent’s listId. Free-plan accounts hold at most 10 agents, drafts included (403 AGENT_LIMIT_REACHED). Every field below is validated by the agents service: a rejected field answers 422 VALIDATION_FAILED, naming it in param and describing every failure in message. listName must not collide with an existing list or agent name (409 LIST_NAME_TAKEN), and starting without enough credits answers 402 INSUFFICIENT_CREDITS without creating anything.

Errors:

422 VALIDATION_FAILED — The request was rejected by validation. Either this endpoint’s own request validation (a malformed body), or the agent config itself: a field missing, out of range or not one of the accepted values, or a business rule broken (an expirationDate that is not in the future, more industries than the kind accepts, a notification count out of range). param names the first offending field and message lists every failure.
409 LIST_NAME_TAKEN — listName is already used by one of your lists or agents. Pick another name.
402 INSUFFICIENT_CREDITS — The workspace does not have enough credits to start this agent. Nothing was created or spent.
403 AGENT_LIMIT_REACHED — Free-plan accounts may hold at most 10 agents, drafts included. Delete an agent or upgrade the plan.
404 LIST_NOT_FOUND — A source list named in listId / listIds does not exist or does not belong to the token owner.
422 AGENT_SOURCE_LIST_EMPTY — The source list holds nothing this agent kind can watch — no LinkedIn URLs, no companies, or no trackable contacts. Fill the list first.
400 INVALID_REQUEST — The agents service rejected the request for a reason this API does not model specifically. The request is not retryable unchanged.
429 RATE_LIMITED — The agents bucket is exhausted: 30 requests per minute or 2,000 per day per token owner, shared by every /business/agents operation (a 429 raised by the agents service is relayed with this code too). Retry after the Retry-After header.
500 UNEXPECTED_ERROR — The agents service failed (5xx, refused service credential, or a timeout after 60s) or the rate limiter was unavailable. Retry later; quote request_id to support.

Requires one of the following token scopes: agents.

POST

business

agents

job-changes-watcher

Create a job changes watcher agent

curl --request POST \
  --url https://api.tryfuse.ai/api/v1/business/agents/job-changes-watcher \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "listName": "<string>"
}
'

import requests

url = "https://api.tryfuse.ai/api/v1/business/agents/job-changes-watcher"

payload = { "listName": "<string>" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({listName: '<string>'})
};

fetch('https://api.tryfuse.ai/api/v1/business/agents/job-changes-watcher', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "agent": {
    "id": "6a8dce4e65fd738c00d89289",
    "type": "job-changes-watcher",
    "name": "Customer job changes",
    "status": "initializing",
    "started": false
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Your API token (af_…) as the Basic-auth username, with an empty password.

Body

application/json

listName

string

required

Name for BOTH the agent and the NEW dedicated results list this watcher creates. Must be unique — never reuse a source list's name; name it after the agent the user is creating.

Minimum string length: 1

start

boolean

default:false

true creates AND activates the agent (spends credits); false (default) saves a draft to activate later.

listId

string

The existing SOURCE list(s) to watch, by id — the people/companies whose changes are tracked.

Minimum string length: 1

listIds

string[]

The existing SOURCE list(s) to watch, by id: the people whose changes are tracked. Each id is a list id from GET /business/lists. Every list you name is watched and their members are unioned, and there is no cap on how many lists; listIds and listId are mutually exclusive (sending both is rejected). Unlike the people and companies watchers, this one REJECTS a repeated id rather than collapsing it (422 VALIDATION_FAILED, "listIds must not contain duplicate list IDs"), so name each list once. Only shared contacts with a LinkedIn URL are watched, so custom contacts are skipped; source lists holding none of them are rejected when the agent starts (422 AGENT_SOURCE_LIST_EMPTY).

Minimum array length: 1

Minimum string length: 1

frequency

enum<integer>

default:30

How often each watched contact is re-checked, in days: 30 (monthly, the default), 7 (weekly) or 1 (daily). Every check costs 50 credits per watched contact, so this is also the billing cadence.

Available options:

30,

7,

1

maxContacts

integer

Cap on the total number of results this agent delivers into its list. Omit for no cap.

maxCreditSpend

integer

Maximum credits one check may cost (1000 to 200000): the watcher watches at most maxCreditSpend / 50 contacts, and the contacts already watched keep their place. Omit for no limit.

Required range: 1000 <= x <= 200000

enrichPhone

boolean

default:false

Also enrich every delivered contact with a phone number. Costs additional credits per contact enriched.

enrichEmail

boolean

default:false

Also enrich every delivered contact with a work email address. Costs additional credits per contact enriched.

Response

Success

agent

object

required

Show child attributes

Lists

Custom columns

Smart columns

Exports

Campaigns

Campaign steps

Knowledge hubs

Analytics

Website intent

Account

Data

Prospect search

Scheduled sends

Campaign templates

Agents

Research

Company search

Saved searches

Folders

Contacts

Create a job changes watcher agent

Authorizations

Body

Response