> ## Documentation Index > Fetch the complete documentation index at: https://docs.fuseai.com/llms.txt > Use this file to discover all available pages before exploring further. # 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/{agentId}, adjust it with PATCH /business/agents/{agentId}, then start it with POST /business/agents/{agentId}/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: - `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. - `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. ## OpenAPI ````yaml /openapi.json post /business/agents/person-discovery-via-filters openapi: 3.1.0 info: title: Fuse Business API version: 1.0.0 description: >- External API for lists, campaigns, prospect search and contacts. Authenticate with your API token as HTTP Basic. All paths are under /api/v1. servers: - url: https://api.tryfuse.ai/api/v1 description: Production security: - basicAuth: [] tags: - name: Lists - name: Custom columns - name: Smart columns - name: Exports - name: Campaigns - name: Knowledge hubs - name: Analytics - name: Website intent - name: Account - name: Prospect search - name: Campaign steps - name: Scheduled sends - name: Campaign templates - name: Agents - name: Research - name: Company search - name: Saved searches - name: Folders - name: Contacts paths: /business/agents/person-discovery-via-filters: post: tags: - Agents summary: Create a person discovery via filters agent description: >- 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/{agentId}, adjust it with PATCH /business/agents/{agentId}, then start it with POST /business/agents/{agentId}/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: - `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. - `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. operationId: createPersonDiscoveryViaFiltersAgent requestBody: required: true content: application/json: schema: type: object properties: start: type: boolean default: false description: >- true creates AND activates the agent (spends credits); false (default) saves a draft to activate later. listName: type: string description: >- 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. regions: type: array items: type: string description: >- 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. industries: type: array items: type: string description: >- 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. currentCompany: type: array items: type: string description: >- 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. pastCompany: type: array items: type: string description: >- 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. currentTitle: type: array items: type: string description: >- 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. pastTitle: type: array items: type: string description: >- 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. companyHeadcount: type: array items: type: string description: >- 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. companyCountries: type: array items: type: string description: >- 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. expirationDate: type: - string - 'null' description: >- 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. maxContacts: type: integer description: >- Cap on the total number of results this agent delivers into its list. Omit for no cap. maxCreditSpend: type: integer minimum: 1000 maximum: 200000 description: >- 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. notificationCount: type: integer description: >- Maximum results the agent may deliver in a single run. Must be a positive multiple of 50. enrichPhone: type: boolean default: false description: >- Also enrich every delivered contact with a phone number. Costs additional credits per contact enriched. enrichEmail: type: boolean default: false description: >- Also enrich every delivered contact with a work email address. Costs additional credits per contact enriched. required: - listName responses: '201': description: Success headers: RateLimit-Limit: schema: type: integer description: Requests permitted in the current window. RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. RateLimit-Reset: schema: type: integer description: Seconds until the current window resets. content: application/json: schema: type: object required: - agent properties: agent: type: object required: - id - type - name - status - started properties: id: type: string description: >- The new agent's id — pass it as `{agentId}` to every other agent operation. type: type: string enum: - person-discovery-via-filters description: >- The agent kind that was created — always this endpoint's own slug. name: type: string description: >- The agent's name, echoed from `listName`; also the name of the results list it delivers into. status: type: string enum: - initializing - processing - active description: >- `initializing` when `start` was false (a draft). When `start` was true, the agent's real status right after starting: `processing` while the provider setup and first run are under way, `active` once it is running. started: type: boolean description: >- Echoes the `start` you sent: false = a draft that still has to be activated; true = already running and already billing. example: agent: id: 6a8dce4e65fd738c00d8927d type: person-discovery-via-filters name: Seed-stage founders in Berlin status: initializing started: false '400': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - basicAuth: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: string message: type: string param: type: - string - 'null' doc_url: type: - string - 'null' request_id: type: - string - 'null' required: - code - message required: - error securitySchemes: basicAuth: type: http scheme: basic description: >- Your API token (`af_…`) as the Basic-auth username, with an empty password. ````