Quickstart

1. Create a free estimate

Every job uses the single target_people operation and an explicit saved persona slug.

curl -X POST https://api.firmintent.com/v1/job-drafts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: estimate-3384253-owners-founders" \
  -H "Content-Type: application/json" \
  -d '{"input":"linkedin.com/company/anthropic","operation":"target_people","persona":"owners-founders"}'

import requests

r = requests.post(
    "https://api.firmintent.com/v1/job-drafts",
    headers={"X-API-Key": "YOUR_API_KEY",
             "Idempotency-Key": "estimate-3384253-owners-founders"},
    json={"input": "linkedin.com/company/anthropic", "operation": "target_people",
          "persona": "owners-founders"},
)
print(r.json())

const r = await fetch("https://api.firmintent.com/v1/job-drafts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY",
             "Idempotency-Key": "estimate-3384253-owners-founders",
             "Content-Type": "application/json" },
  body: JSON.stringify({ input: "linkedin.com/company/anthropic",
                         operation: "target_people", persona: "owners-founders" }),
});
console.log(await r.json());

The response is 202 { "draft_id": "…", "revision": 1, "state": "matching_company" }. This free preflight does not reserve credits, create an executable job, or appear in Request History. Idempotency-Key is required for create and confirm. Reusing the same key and request returns the original response; reusing it for a different request returns 409 idempotency_conflict. Keys may contain 1–128 characters.

2. Poll the estimate

curl https://api.firmintent.com/v1/job-drafts/<draft_id> -H "X-API-Key: YOUR_API_KEY"

Continue while state is matching_company. A ready estimate includes the server-authored company/headcount, wallet and quote:

{
  "draft_id": "…",
  "revision": 1,
  "state": "quote_ready",
  "company": {"company_id": 3384253, "name": "Acme", "employees_count": 42},
  "quote": {
    "pricing_version": "employee_linear_v1",
    "employee_count": 42,
    "data": {"units": 126, "unit_scale": 1000},
    "matching": {"units": 42, "unit_scale": 1000},
    "total": {"units": 168, "unit_scale": 1000}
  },
  "quote_fingerprint": "…",
  "wallet": {
    "balance": {"units": 12000, "unit_scale": 1000},
    "reserved": {"units": 0, "unit_scale": 1000},
    "available": {"units": 12000, "unit_scale": 1000},
    "version": 1
  }
}

not_found, no_employees and too_large are typed free outcomes and cannot be confirmed. metadata_unavailable may be retried through its draft action.

3. Confirm the reviewed quote

curl -X POST https://api.firmintent.com/v1/job-drafts/<draft_id>/confirm \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: confirm-estimate-3384253-v1" \
  -H "Content-Type: application/json" \
  -d '{"revision":1,"quote_fingerprint":"<quote_fingerprint>"}'

A new search returns 201 with outcome: "created" and its job. Exact running/result reuse may return 200 without a second reservation. If the price increased, review the replacement in 409 quote_changed; the server made no reservation. A lower revalidated price is applied automatically.

4. Poll the confirmed job

curl https://api.firmintent.com/v1/jobs/<job_id> -H "X-API-Key: YOUR_API_KEY"

While work is delayed, status remains processing:

{"status":"processing","processing_state":"delayed","stage":"verify_candidates","next_retry_at":"…"}

The immutable final result is inline:

{
  "job_id": "…",
  "status": "done",
  "company": {"id": 3384253, "name": "Acme", "company_language": "en"},
  "persona": {"slug": "owners-founders", "name": "Owners & founders"},
  "team_scanned": 42,
  "preliminary_candidates": 3,
  "target_people_count": 1,
  "target_people": [{
    "rank_in_company": 1,
    "is_decision_maker": true,
    "why": "Founder with current ownership responsibility and active company engagement.",
    "person": {"name": "Jane Doe", "gender": "female", "outreach_language": "en"},
    "professional": {"tier": "owner", "role": "Founder and CEO", "belongs_to_company": "confirmed"},
    "contact": {"email": {"address": "jane@acme.com", "status": "valid", "source": "verified"}}
  }],
  "billing": {
    "pricing_version": "employee_linear_v1",
    "captured": {
      "data": {"units": 126, "unit_scale": 1000},
      "matching": {"units": 42, "unit_scale": 1000},
      "total": {"units": 168, "unit_scale": 1000}
    }
  }
}

Re-polling returns the same published result version and never charges again.

Webhook instead of polling

Add a public HTTPS callback_url to the draft body. A saved dashboard webhook is HMAC-signed; all deliveries include a stable event ID. Failed deliveries retry from a durable outbox with jitter for up to 24 hours. Receivers should still be idempotent by event ID.

Cancel a job

POST /v1/jobs/{job_id}/cancel fences further work (idempotent). The active reservation is released by durable settlement; already captured work is not refunded and an already-published result cannot be cancelled.

Job outcomes

Public statuses are processing, done, not_found, no_employees, no_people_found, too_large, failed, and cancelled. Terminal failure and no_people_found release the reservation. A published result with named targets captures its immutable estimate; there is no after-the-fact headcount recalculation. The size gate remains over 100 employees for non-exempt plans. pro, internal, unlimited, and enterprise bypass it.

Personas — full guide

Manage targets and learn about the immutable Owners & founders system persona.

Get started

Guides

Billing & errors

1. Create a free estimate

2. Poll the estimate

3. Confirm the reviewed quote

4. Poll the confirmed job

Webhook instead of polling

Cancel a job

Job outcomes

Personas — full guide

​1. Create a free estimate

​2. Poll the estimate

​3. Confirm the reviewed quote

​4. Poll the confirmed job

​Webhook instead of polling

​Cancel a job

​Job outcomes

Personas — full guide

1. Create a free estimate

2. Poll the estimate

3. Confirm the reviewed quote

4. Poll the confirmed job

Webhook instead of polling

Cancel a job

Job outcomes