ProspectChief API

Account & authentication

Authenticate every request with a Bearer API key:

Authorization: Bearer YOUR_API_KEY

Create keys in Settings → API keys. Each key carries the permissions you grant when creating it:

Security: Keep API keys server-side. Never embed them in browser JavaScript, a mobile app, or a browser extension bundle. Keys can be revoked at any time from Settings. Resources belonging to other accounts return 404, never their data.

GET /account

Returns the plan, products, timezone, verification credit balance, entitlements and connected devices. Credits: none.

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.prospectchief.com/api/v1/account"

const res = await fetch("https://app.prospectchief.com/api/v1/account", {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
const data = await res.json();

import requests
r = requests.get(
    "https://app.prospectchief.com/api/v1/account",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(r.json())

Projects

Projects group leads. purpose is leads (Extractor contacts) or maps (Maps businesses). GET /projects defaults to purpose=leads; pass purpose=maps or purpose=all.

Each purpose has its own quota on Free plans (Maps: 3 projects on Free, 100 on Maps Pro by default; Extractor: see entitlements.projects_max). When the quota is reached, POST /projects returns 403 with error: project_limit_reached, limit, used and, for Free accounts, an upgrade_url.

curl -sS -X POST "https://app.prospectchief.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Plumbers — Austin","purpose":"maps"}'

• GET /projects?purpose=maps&page=1&per_page=50 — list
• GET /projects/{id} · PATCH (name, autosave) · DELETE
• GET /projects/{id}/export?format=csv|xlsx — download contacts (CSV has a UTF-8 BOM; cells starting with = + - @ are neutralised)

Maps businesses & enrichment

Businesses are captured in the browser by the Bing Maps and Google Maps Lead Finder extensions and saved to Maps projects. The API lets you list, filter, save and enrich saved businesses. Extension-only: live capture from the map, the collect handshake and the Maps Free email reveal. There is no server-side Google/Bing scraping endpoint.

GET /businesses

Paginated list of all saved businesses with filters: project_id, platform (bing_maps|google_maps), has_email, enrichment_status, q (name, website domain or locality), updated_since, page, per_page (≤100).

curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.prospectchief.com/api/v1/businesses?platform=bing_maps&has_email=1&per_page=100"

Each record carries coherent source fields regardless of platform:

• GET /businesses/{id} — detail
• GET /projects/{id}/businesses — businesses on one Maps project (extension-compatible shape)
• POST /projects/{id}/businesses — save up to 200 businesses (name, source_platform, source_place_id, website_url, address, phone, coordinates, rating, review_count, emails[]). Businesses with a website are queued for website enrichment within plan limits.
• POST /projects/{id}/businesses/enrich · POST …/{business}/enrich · POST …/{business}/enrich/cancel

import requests
page = 1
while True:
    r = requests.get("https://app.prospectchief.com/api/v1/businesses",
                     params={"has_email": 1, "page": page, "per_page": 100},
                     headers={"Authorization": "Bearer YOUR_API_KEY"})
    r.raise_for_status()
    body = r.json()
    for b in body["data"]:
        print(b["name"], b["source"]["platform"], [e["email"] for e in b["emails"]])
    if page >= body["meta"]["last_page"]:
        break
    page += 1

Extractor contacts & imports

• GET /contacts?q=&project_id=&page=&per_page= — list
• POST /contacts — save up to 1000 contacts (email, name, company_name, source_url, source_type); optional project_id/project_ids
• PATCH /contacts/{id} · DELETE /contacts/{id}
• GET /projects/{id}/contacts · POST · DELETE …/contacts/{contact}
• GET /contacts/mail-summary?project_id= — Domain Mail Ready aggregates
• Imports: POST /imports → POST /imports/{job}/batches (idempotent by batch_index) → POST /imports/{job}/complete; GET /imports/{job} for progress

curl -sS -X POST "https://app.prospectchief.com/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":12,"contacts":[{"email":"[email protected]","name":"Jane Doe","source_url":"https://example.com/team"}]}'

Exclusions

Rules from Settings → Exclusions are applied server-side to every save path — POST /contacts, POST /projects/{id}/contacts, imports and Maps website enrichment. Matching addresses are skipped, counted under rejected_by_reason.user_exclusion, and are never charged by verification. Existing saved records are not deleted when a rule is added.

Email verification

Two layers: Mail Intelligence (domain routing / classification, free) and metered mailbox verification. Requires a key with the email_validate permission.

POST /validate

curl -sS -X POST "https://app.prospectchief.com/api/v1/validate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","mailbox_verification":true}'

await fetch("https://app.prospectchief.com/api/v1/validate", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ email: "[email protected]", mailbox_verification: true })
});

import requests
requests.post(
    "https://app.prospectchief.com/api/v1/validate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"email": "[email protected]", "mailbox_verification": True},
)

Mailbox dispositions: valid, invalid, catch_all, unknown. Domain Mail Ready (Mail Intelligence) means the domain has a usable mail route; it is not mailbox verification and does not prove the local part exists.

POST /validate/batch

Up to 200 emails[] per request; same mailbox_verification semantics.

Project verification

Verify the mailboxes of a whole project (Extractor contacts or Maps business emails) with the same planner, exclusions and credit ledger as the web workspace.

1. GET /projects/{id}/verification/preview?force_reverify=0 — cost preview: total, already_verified_fresh, needs_verification, eligible, estimated_credits, reverify_estimated_credits, available_credits, excluded_*, up_to_date, insufficient_credits. Nothing is created or charged.
2. POST /projects/{id}/verification with an Idempotency-Key header (required) and optional force_reverify, start (default true). Returns 201 with the job; replaying the same key returns the existing job with 200 and never creates or charges twice. 402 insufficient_verification_balance when credits are short, 409 up_to_date when every contact is fresh, 422 nothing_to_verify, 503 when the service is paused.
3. GET /verification/jobs/{public_id} — poll status (status, percent, counts, credits_reserved, credits_charged, queue_position); GET /verification/jobs lists jobs.

curl -sS -X POST "https://app.prospectchief.com/api/v1/projects/12/verification" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: crm-sync-2026-10-12-run-1" \
  -H "Content-Type: application/json" \
  -d '{"force_reverify":false}'

Credits

• Verification credits are one shared balance for the whole account (Extractor and Maps). Subscriptions (FEE Pro, Maps Pro) are separate products and are not merged; an active Pro subscription of either product gives the same single credit-pack discount — it never stacks.
• Mailbox verification is metered. Mail Intelligence alone is never charged.
• Fresh results (checked within the freshness window) are reused without a new provider operation and are never charged again. Only new or stale addresses consume credits; Verify all / Reverify must be requested explicitly (force_reverify).
• Credits are reserved when a job starts (credits_reserved) and settled per chargeable result (credits_charged); operational provider failures do not invent an invalid disposition and are not charged.
• Insufficient credits reject the operation with 402 and balance.available / balance.required — there is no silent free verification.
• When the customer service gate is disabled, mailbox verification requests return 503 with mailbox_verification_unavailable.

Errors & rate limits

{
  "error": "insufficient_verification_balance",
  "message": "Not enough mailbox verification credits for this job.",
  "balance": { "available": 0, "required": 25 }
}

Rate limits: account endpoints allow 180 requests per minute per API key; validation endpoints use a separate per-key limiter. Batch where possible (per_page=100, /validate/batch, imports).

Webhooks are not offered in v1 — poll GET /verification/jobs/{id} and GET /imports/{job}.

This documentation page is public. API execution always requires authentication. CORS is not enabled for API keys: call the API from your server, not from a web page.

All endpoints

Generated from the same contract as openapi.json.

Account

Maps businesses

Extractor contacts

Imports

Projects

Email verification

Extension-only (not a general API): POST /auth/extension/exchange, POST /extension/events, POST /businesses/collect, POST /businesses/{id}/emails/reveal, GET /contacts/activity; website-only: /public/*, /mx/*, /checkout/intents, /admission-policy.