curl --request POST \
--url https://api.tryfuse.ai/api/v1/business/agents/person-discovery-via-filters \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"listName": "<string>"
}
'import requests
url = "https://api.tryfuse.ai/api/v1/business/agents/person-discovery-via-filters"
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/person-discovery-via-filters', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"agent": {
"id": "6a8dce4e65fd738c00d8927d",
"type": "person-discovery-via-filters",
"name": "Seed-stage founders in Berlin",
"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>"
}
}Create a person discovery via filters agent
Creates a Person discovery via filters agent (person-discovery-via-filters). Delivers people matching the filter set; at least one filter must be non-empty. 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, credits are checked and spent, 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:
422VALIDATION_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 (anexpirationDatethat is not in the future, more industries than the kind accepts, a notification count out of range).paramnames the first offending field andmessagelists every failure.409LIST_NAME_TAKEN—listNameis already used by one of your lists or agents. Pick another name.402INSUFFICIENT_CREDITS— The workspace does not have enough credits to start this agent. Nothing was created or spent.403AGENT_LIMIT_REACHED— Free-plan accounts may hold at most 10 agents, drafts included. Delete an agent or upgrade the plan.400INVALID_REQUEST— The agents service rejected the request for a reason this API does not model specifically. The request is not retryable unchanged.429RATE_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 theRetry-Afterheader.500UNEXPECTED_ERROR— The agents service failed (5xx, refused service credential, or a timeout after 60s) or the rate limiter was unavailable. Retry later; quoterequest_idto support.
Requires one of the following token scopes: agents.
curl --request POST \
--url https://api.tryfuse.ai/api/v1/business/agents/person-discovery-via-filters \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"listName": "<string>"
}
'import requests
url = "https://api.tryfuse.ai/api/v1/business/agents/person-discovery-via-filters"
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/person-discovery-via-filters', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"agent": {
"id": "6a8dce4e65fd738c00d8927d",
"type": "person-discovery-via-filters",
"name": "Seed-stage founders in Berlin",
"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
Your API token (af_…) as the Basic-auth username, with an empty password.
Body
Name for BOTH the agent and the results list it creates. Must be unique across your agents: a name already in use is rejected with 409 LIST_NAME_TAKEN.
true creates AND activates the agent (spends credits); false (default) saves a draft to activate later.
Where the person is located, as a LinkedIn geography: either a country ("United States") or a sub-national area ("California, United States"). Use exact values from GET /business/agents/autocomplete?field=region. The upstream stores the string as sent and never checks it against a list, so any other value is accepted, the create still answers 201, and the agent then silently matches nothing. Multiple regions are OR-joined (a person in any of them matches) and there is no cap.
Industry the person works in. Use exact values from GET /business/agents/autocomplete?field=industry (for example "Software Development", "Financial Services"). Any other wording is first resolved to the closest supported LinkedIn industry ("tech" becomes "Technology, Information and Internet"), and a value with no match is dropped rather than rejected, so the filter silently widens instead of failing. Multiple industries are OR-joined (a person in any of them matches) and there is no cap.
Current employer of the people to discover, as a company NAME or DOMAIN, for example ["Google"] or ["google.com"]. Free text resolved by the provider, so a name it cannot resolve is accepted, the create still answers 201, and the agent then silently matches nothing; a domain is the unambiguous form. Multiple values are OR-joined (a person at any of them matches) and there is no cap.
Past employer of the people to discover, as a company NAME or DOMAIN, for example ["Google"] or ["google.com"]. Free text resolved by the provider, so a name it cannot resolve is accepted, the create still answers 201, and the agent then silently matches nothing; a domain is the unambiguous form. Multiple values are OR-joined (a person who worked at any of them matches) and there is no cap.
Current job title of the people to discover. Use exact values from GET /business/agents/autocomplete?field=title (for example "Vice President of Sales", "CEO"). The upstream stores the string as sent and never checks it against a list, so any other value is accepted, the create still answers 201, and the agent then silently matches nothing. Multiple titles are OR-joined (a person holding any of them matches) and there is no cap.
A job title anywhere in the person's PAST work history. Use exact values from GET /business/agents/autocomplete?field=title (for example "Vice President of Sales", "CEO"). The upstream stores the string as sent and never checks it against a list, so any other value is accepted, the create still answers 201, and the agent then silently matches nothing. Multiple titles are OR-joined (a person who held any of them matches) and there is no cap.
Size of the person's current employer, as a headcount bucket. Use one of exactly: 1-10, 11-50, 51-200, 201-500, 501-1,000, 1,001-5,000, 5,001-10,000, 10,001+ (the commas and the exact spacing are part of the value: "500-1000" is not a bucket). The upstream stores the string as sent and never checks it against a list, so any other value is accepted, the create still answers 201, and the agent then silently matches nothing. Multiple buckets are OR-joined (a person whose employer is in any listed band matches) and there is no cap.
Headquarters country of the person's current employer. Accepted values are full English country names, for example "United States", "United Kingdom", "Germany" — the vocabulary the app's own agent form sends for this filter. ISO codes such as "US" are not country names and match nothing, and no lookup endpoint serves this vocabulary: the agents autocomplete has no country field, and its region field returns LinkedIn geographies that include sub-national areas such as "California, United States", which are not country names. Nothing is checked against a list upstream, so an unrecognised value is accepted, the create still answers 201, and the agent then silently matches nothing. Multiple countries are OR-joined (a person whose employer sits in any of them matches) and there is no cap.
Date the agent stops running, as YYYY-MM-DD (for example "2026-12-31"), and in the future. Pass null to run until you pause or delete it; omit it for the default of one month from creation.
Cap on the total number of results this agent delivers into its list. Omit for no cap.
Maximum credits this agent may spend in a single run or refresh (1000 to 200000); delivery-driven monitors stop once their total delivered results reach it. Omit for no limit.
1000 <= x <= 200000Maximum results the agent may deliver in a single run. Must be a positive multiple of 50.
Also enrich every delivered contact with a phone number. Costs additional credits per contact enriched.
Also enrich every delivered contact with a work email address. Costs additional credits per contact enriched.
Response
Success
Show child attributes
Show child attributes