--- title: "Create a company headcount growth agent" method: POST path: "/business/agents/company-headcount-growth" tags: ["Agents"] --- # Create a company headcount growth agent `POST /business/agents/company-headcount-growth` ## Request - Base URL: `https://api.tryfuse.ai/api/v1` - URL: `https://api.tryfuse.ai/api/v1/business/agents/company-headcount-growth` - Auth: HTTP basic Creates a Company headcount growth agent (`company-headcount-growth`). Delivers companies whose headcount grew within `companyHeadcountGrowth` percent. 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. ## Request body - object - `start` boolean: true creates AND activates the agent (spends credits); false (default) saves a draft to activate later. - `listName` string, required: 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. - `companyHeadcountGrowth` object, required: The year-over-year headcount growth band to match, in PERCENT: {"min": 10, "max": 50} means companies that grew 10% to 50% YoY. Accepted values: any two numbers of 0 or more, with `min` less than or equal to `max` and no upper limit on `max`. Both bounds are required whenever the object is sent. - `min` number, required: Minimum year-over-year headcount growth, as a percentage (10 means 10%). - `max` number, required: Maximum year-over-year headcount growth, as a percentage (40 means 40%). - `industries` string[], required: Industry of the company. 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. Exactly one value is allowed here (min 1, max 1); to cover several, run one agent per value. - `regions` string[], required: Headquarters location of the company, 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. Exactly one value is allowed here (min 1, max 1); to cover several, run one agent per value. - `companyHeadcount` string[], required: Size of the company, 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. Exactly one value is allowed here (min 1, max 1); to cover several, run one agent per value. - `companyCountries` string[]: Deprecated: accepted for backward compatibility and never forwarded to the provider, so arbitrary values here change nothing about what the agent matches. Filter headquarters location with `regions` instead. Multiple values neither widen nor narrow the agent: the whole array is dropped before the provider call, so no OR or AND combination applies and no cap is enforced. - `annualRevenue` object: Annual-revenue band of the company, in MILLIONS of USD: {"min": 1000, "max": 10000} means $1B to $10B. Both bounds are required whenever the object is sent, and `subFilter` must be one of exactly: USD, the default and the only currency the provider supports. Omit the whole object for no revenue filter. - `min` number, required: Minimum annual revenue, in MILLIONS of the `subFilter` currency (1000 means $1B). - `max` number, required: Maximum annual revenue, in MILLIONS of the `subFilter` currency (10000 means $10B). - `subFilter` 'USD': Currency the revenue bounds are expressed in. Only USD is supported. - `expirationDate` string, nullable: 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` integer: Cap on the total number of results this agent delivers into its list. Omit for no cap. - `maxCreditSpend` integer: 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` integer: Maximum results the agent may deliver in a single run. Must be a positive multiple of 50. ## Response `201` Success - object - `agent` object, required - `id` string, required: The new agent's id — pass it as `{agentId}` to every other agent operation. - `type` 'company-headcount-growth', required: The agent kind that was created — always this endpoint's own slug. - `name` string, required: The agent's name, echoed from `listName`; also the name of the results list it delivers into. - `status` 'initializing' | 'processing' | 'active', required: `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` boolean, required: Echoes the `start` you sent: false = a draft that still has to be activated; true = already running and already billing. ## Other responses - `400`: Error - `401`: Error - `402`: Error - `403`: Error - `404`: Error - `409`: Error - `422`: Error - `429`: Error - `500`: Error --- [API](https://skmtc.dev/fuseai/apis/fuse-business-api.md) · [All operations](https://skmtc.dev/fuseai/apis/fuse-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fuseai/apis/fuse-business-api/revisions/50d95e0536f4?raw)