> ## Documentation Index > Fetch the complete documentation index at: https://docs.firmintent.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a persona > Save a target audience. `definition` is plain-language criteria (roles, seniority, function, exclusions) Gemini applies to company people — not a keyword filter. The `slug` is derived from the name (unique per account) and is what you pass as `persona` on `POST /v1/jobs`. ## OpenAPI ````yaml https://api.firmintent.com/openapi.json post /v1/personas openapi: 3.1.0 info: title: firmintent API description: > Give firmintent a **LinkedIn company and persona** — get back the **right people**. You submit a company — a **LinkedIn company URL** (`…/company/`) or a **bare numeric company id**; we scan and broadly enrich its roster, find likely persona candidates, verify the shortlist, and return a ranked target list. (Bare name/domain lookup is a later layer — not accepted yet.) Jobs run **asynchronously** (minutes) — you either poll `GET /v1/jobs/{id}` or receive a **webhook**. All endpoints are versioned under **`/v1`**. Pin the version; new fields are added within `/v1`, breaking changes ship under a new `/vN`. ### Authentication Every request needs an API key in the `X-API-Key` header. Generate yours in the [dashboard](https://app.firmintent.com/dashboard). `POST /v1/jobs` spends money, so it is never anonymous. ### The flow — two calls 1. `POST /v1/jobs` `{ "input": "linkedin.com/company/", "operation": "target_people", "persona": "owners-founders" }` → `202 { job_id }` 2. Poll `GET /v1/jobs/{job_id}` until `status: "done"` — that response contains `target_people[]` inline. No third call. Re-polling a finished job returns the same result (idempotent, already paid for), so a lost response never costs a new job. ### Webhook (optional — instead of polling) Pass `callback_url` on `POST /v1/jobs`. When the job is done we `POST` that URL with the full result: `{ job_id, company_id, company, status: "done", target_people_count, target_people[] }`. You just need an HTTPS endpoint on your side that returns `2xx`. contact: name: firmintent url: https://firmintent.com/ version: 1.0.0 servers: - url: https://api.firmintent.com description: Production security: [] tags: - name: jobs description: Submit and track target-people jobs. - name: account description: Your credit balance, tier and usage. - name: personas description: Saved target audiences used by persona-first jobs. paths: /v1/personas: post: tags: - personas summary: Create a persona description: >- Save a target audience. `definition` is plain-language criteria (roles, seniority, function, exclusions) Gemini applies to company people — not a keyword filter. The `slug` is derived from the name (unique per account) and is what you pass as `persona` on `POST /v1/jobs`. operationId: create_persona_v1_personas_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonaCreate' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Persona' '400': description: Missing name or definition. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: PersonaCreate: properties: name: type: string title: Name description: Display name. The slug is derived from it (unique per account). examples: - Marketing leaders definition: type: string title: Definition description: >- Plain-language criteria the persona LLM judges each roster member against. Describe who to KEEP, including any exclusions. examples: - >- Heads of marketing or growth with budget authority — not junior or freelance. make_default: type: boolean title: Make Default description: Make this the account's default persona. default: false type: object required: - name - definition title: PersonaCreate Persona: properties: slug: type: string title: Slug description: >- Stable id, unique per account — pass this as the `persona` on POST /v1/jobs. examples: - marketing-leaders name: type: string title: Name description: Display name. examples: - Marketing leaders definition: type: string title: Definition description: >- Plain-language criteria the persona LLM judges each roster member against. examples: - >- Heads of marketing or growth with budget authority — not junior or freelance. is_default: type: boolean title: Is Default description: Whether this is the account's default persona. default: false is_system: type: boolean title: Is System description: Immutable system persona; it cannot be edited or deleted. default: false created_at: anyOf: - type: string - type: 'null' title: Created At description: ISO 8601 UTC. examples: - '2026-07-20T09:00:00Z' type: object required: - slug - name - definition title: Persona description: >- A saved target audience. `definition` is plain-language criteria our LLM judges each decision maker against (roles, seniority, function, exclusions) — not a keyword filter. Reference it on `POST /v1/jobs` by `slug` to keep only the matches; it never changes the price. ErrorResponse: properties: error: $ref: '#/components/schemas/ErrorDetail' type: object required: - error title: ErrorResponse description: >- Every non-2xx response has this shape: a single `error` object. Consistent across all status codes. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ErrorDetail: properties: code: type: string title: Code description: Stable machine-readable error code. examples: - insufficient_credits message: type: string title: Message description: Human-readable explanation. examples: - You're out of credits. Top up to run jobs. balance: anyOf: - type: integer - type: 'null' title: Balance description: Your current credit balance (present on credit errors). limit: anyOf: - type: integer - type: 'null' title: Limit description: Your plan's concurrency limit (present on concurrency errors). type: object required: - code - message title: ErrorDetail description: >- A single error. Branch on `code` (stable, machine-readable) — never on `message` (human text that may change). Extra fields carry context: `balance` on credit errors, `limit` on concurrency errors. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyHeader: type: apiKey description: Your brk_live_ API key. in: header name: X-API-Key ````