Quickstart

1. Submit a company and persona

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

curl -X POST https://api.bossradar.com/v1/jobs \
  -H "X-API-Key: brk_live_..." \
  -H "Idempotency-Key: company-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.bossradar.com/v1/jobs",
    headers={"X-API-Key": "brk_live_...",
             "Idempotency-Key": "company-3384253-owners-founders"},
    json={"input": "linkedin.com/company/anthropic", "operation": "target_people",
          "persona": "owners-founders"},
)
print(r.json())

const r = await fetch("https://api.bossradar.com/v1/jobs", {
  method: "POST",
  headers: { "X-API-Key": "brk_live_...",
             "Idempotency-Key": "company-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 { "job_id": "…", "status": "processing" }. Missing persona returns 400 persona_required; an unknown slug returns 400 persona_not_found. Idempotency-Key is optional but recommended for every submission. Reusing the same key and request under one API client returns the original job; reusing it for a different request returns 409 idempotency_conflict. Keys may contain 1–128 characters.

2. Poll the same job

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

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"}}
  }],
  "credits_charged": 1,
  "credits_balance": 9
}

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

Webhook instead of polling

Add a public HTTPS callback_url to the submit body. A saved dashboard webhook is HMAC-signed; all deliveries include a stable X-Bossradar-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 stops further work and marks the job cancelled (idempotent). Cancelling is always free and immediately frees your concurrency slot. A job that already finished is returned unchanged — a paid result cannot be cancelled.

Job outcomes

Public statuses are processing, done, not_found, no_employees, no_people_found, too_large, failed, and cancelled. Every terminal free outcome returns credits_charged: 0; a completed metered result, including zero persona matches, returns 1. Unmetered plans report the actual debit, 0. 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. Submit a company and persona

2. Poll the same job

Webhook instead of polling

Cancel a job

Job outcomes

Personas — full guide

​1. Submit a company and persona

​2. Poll the same job

​Webhook instead of polling

​Cancel a job

​Job outcomes

Personas — full guide

1. Submit a company and persona

2. Poll the same job

Webhook instead of polling

Cancel a job

Job outcomes