> ## 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. # Credit balance and movement history > Your credit balance + the paginated ledger — every movement (signup bonus, purchase, per-job spend, refund), newest first. The append-only ledger is the source of truth for the balance (§credits); a job spend's `ref` is its `job_id`. `limit` (max 200) + `skip` paginate. ## OpenAPI ````yaml https://api.firmintent.com/openapi.json get /v1/credits 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/credits: get: tags: - account summary: Credit balance and movement history description: >- Your credit balance + the paginated ledger — every movement (signup bonus, purchase, per-job spend, refund), newest first. The append-only ledger is the source of truth for the balance (§credits); a job spend's `ref` is its `job_id`. `limit` (max 200) + `skip` paginate. operationId: credits_v1_credits_get parameters: - name: limit in: query required: false schema: type: integer default: 50 title: Limit - name: skip in: query required: false schema: type: integer default: 0 title: Skip responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreditsResponse' '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: CreditsResponse: properties: balance: type: integer title: Balance description: Current credit balance (equals the sum of the ledger). examples: - 7 tier: anyOf: - type: string - type: 'null' title: Tier examples: - free count: type: integer title: Count description: Total ledger rows (for pagination). examples: - 12 entries: items: $ref: '#/components/schemas/CreditEntry' type: array title: Entries description: Credit movements, newest first. type: object required: - balance - count - entries title: CreditsResponse 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 CreditEntry: properties: amount: type: integer title: Amount description: 'Signed: + granted, − spent.' examples: - -5 reason: type: string title: Reason description: >- signup_bonus | purchase | subscription_grant | promo | spend | refund | expiry examples: - spend ref: anyOf: - type: string - type: 'null' title: Ref description: What it's tied to — a job_id (spend) or a payment/promo id (grant). at: anyOf: - type: string - type: 'null' title: At description: ISO 8601 UTC timestamp. examples: - '2026-07-19T16:00:35Z' type: object required: - amount - reason title: CreditEntry 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 ````