> ## 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.

# Your balance and usage

> Your credit balance + tier + recent ledger. Credits are spent per job (§billing — the billable
unit is POST /jobs). Sync read, not an operation.



## OpenAPI

````yaml https://api.firmintent.com/openapi.json get /v1/account
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/<slug-or-id>`)
    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/<slug>", "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/account:
    get:
      tags:
        - account
      summary: Your balance and usage
      description: >-
        Your credit balance + tier + recent ledger. Credits are spent per job
        (§billing — the billable

        unit is POST /jobs). Sync read, not an operation.
      operationId: account_v1_account_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    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.
    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.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Your brk_live_ API key.
      in: header
      name: X-API-Key

````