Authentication

Every /api/v1/* request requires the X-API-Key header.

X-API-Key: pk_live_YOUR_KEY

Key format

pk_live_ + 64 hex characters (32 random bytes). Generated in Settings, shown once at creation, SHA-256-hashed at rest. We never store the plaintext.

Scoping

Keys inherit their owner's role + scoping:

• sales_rep keys see only the rep's assigned companies/contacts/deals
• admin / super_admin keys see everything in the org

Revocation

Revoke any key from Settings — soft-delete (preserves audit trail of when the key was used). Revoked keys 401 immediately on the next request.

Rate limits

v1 is uncapped — we'll add per-key throttling if any single key starts hammering the API. Until then, please be reasonable: a few req/sec is fine, sustained 100+ req/sec will get noticed.

Companies API

Base path: https://YOUR-PROSPECTOR-HOST/api/v1/companies

List companies

GET /api/v1/companies?limit=50&offset=0&status=active&search=pools

Query params: limit (1-200, default 50), offset, status (new/active/sequencing/...), search (matches name + website).

Get one

GET /api/v1/companies/{id}

Create / upsert

POST /api/v1/companies
{
  "name": "Smith Pools",
  "website": "smithpools.com",
  "phone": "+17025551234",
  "address": "123 Lake Mead Blvd",
  "city": "Las Vegas",
  "state": "NV",
  "business_type": "pool builders",
  "custom_fields": {
    "pool_type": "fiberglass",
    "service_radius_miles": 50
  }
}

Upsert by canonical domain when website is set + an existing record matches. Existing fields are preserved (never clobbered) on the second write.

Response: {"created": true|false, "company": {...}}. created: true fires the company.created webhook event.

Update

PATCH /api/v1/companies/{id}
{
  "phone": "+17025559999",
  "status": "qualified",
  "custom_fields": {"pool_type": "concrete"}
}

Custom field values: only keys matching active Additional Information definitions (Settings → Additional Information Fields) are accepted. Empty string deletes the key.

Response shape

{
  "id": 42,
  "name": "Smith Pools",
  "website": "smithpools.com",
  "domain": "smithpools.com",
  "phone": "+17025551234",
  "address": "...",
  "city": "Las Vegas",
  "state": "NV",
  "rating": 4.6,
  "review_count": 47,
  "business_type": "pool builders",
  "status": "active",
  "industry": "Construction",
  "employee_count": 12,
  "company_size": "11-50",
  "founded": "2008",
  "linkedin_url": "https://linkedin.com/company/smith-pools",
  "facebook_url": "https://facebook.com/smithpools",
  "instagram_url": "https://instagram.com/smithpools",
  "youtube_url": null,
  "tiktok_url": null,
  "lead_score": 78,
  "lead_score_tier": "hot",
  "custom_fields": {"pool_type": "fiberglass"},
  "assigned_to": 3,
  "created_at": "2026-05-08T19:42:11+00:00"
}

Contacts API

Base path: /api/v1/contacts

Create / upsert

Either company_id OR company_domain is required. Upserts by email within that company.

POST /api/v1/contacts
{
  "company_domain": "smithpools.com",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john@smithpools.com",
  "phone": "+17025550100",
  "title": "Owner",
  "linkedin_url": "https://linkedin.com/in/johnsmith",
  "is_primary": true,
  "custom_fields": {
    "personal_email_alt": "john@gmail.com"
  }
}

Get one

GET /api/v1/contacts/{id}

Update

PATCH /api/v1/contacts/{id}
{
  "title": "CEO",
  "phone": "+17025550101",
  "custom_fields": {"linkedin_premium": true}
}

Same custom-field rules as Companies API — only active definitions accepted, empty string deletes the key.

Webhooks

Outbound HTTP POSTs to your endpoint when subscribed events fire. Signed with HMAC-SHA256 so you can verify requests came from us.

Setup

1. Settings → + New Webhook → paste your URL, check the events you want
2. Copy the signing secret (shown once) into your endpoint config
3. Verify signatures on every request

Headers we send

Content-Type:        application/json
X-Webhook-Event:     company.created
X-Webhook-Signature: sha256=<hex_hmac_of_raw_body>
X-Webhook-Delivery:  <random_token>
User-Agent:          BMP-Prospector-Webhooks/1.0

X-Webhook-Delivery is unique per attempt — store it on your end + dedupe so retries don't double-process.

Verify the signature (Python)

import hmac, hashlib

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

# In your endpoint:
sig = request.headers["X-Webhook-Signature"]
if not verify(MY_WEBHOOK_SECRET, request.body_raw, sig):
    return 401, "bad signature"

Verify the signature (Node.js)

const crypto = require('crypto');

function verify(secret, rawBody, header) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(header)
  );
}

Body shape (every event)

{
  "event": "company.created",
  "delivery_id": "abc123_unique_per_attempt",
  "occurred_at": "2026-05-08T19:42:11+00:00",
  "data": { ... event-specific payload ... }
}

Delivery + retry

v1 is best-effort: 10s timeout, single attempt. Failed deliveries are visible in Settings → Webhooks (last status, last error, failure count). Retry queue lands in v2.

Respond with any 2xx to acknowledge. 4xx / 5xx / network errors bump the failure counter; we don't auto-disable.

Test without real events

Settings → Webhooks → Test (per webhook). Fires a synthetic webhook.test event with a token + your email. Use it to verify signature handling end-to-end.

Event Reference (v1)

Subscribe by name. Empty event list on a webhook = receive ALL events.

company.created

Fires when a new Company row is created. Upserts of existing companies do not fire this — only true inserts.

{
  "event": "company.created",
  "delivery_id": "...",
  "occurred_at": "...",
  "data": {
    "id": 42,
    "name": "Smith Pools",
    "website": "smithpools.com",
    "domain": "smithpools.com",
    "phone": "+17025551234",
    "city": "Las Vegas",
    "state": "NV",
    "business_type": "pool builders",
    "status": "new",
    "lead_score": 0,
    "lead_score_tier": "cold",
    "custom_fields": {},
    "created_at": "..."
  }
}

contact.created

Fires when a new Contact row is created. Same dedup rule as company.created — true inserts only.

{
  "event": "contact.created",
  "data": {
    "id": 88,
    "company_id": 42,
    "first_name": "John", "last_name": "Smith",
    "title": "Owner",
    "email": "john@smithpools.com",
    "phone": "+17025550100",
    "phone_type": "mobile",
    "linkedin_url": "...",
    "is_primary": true,
    "email_status": "valid",
    "custom_fields": {}
  }
}

email.replied

Fires when a real prospect reply lands (auto-responses + OOO are skipped). Sentiment classification fires async after this — sentiment is NOT in the event payload because it's not classified yet at fire time.

{
  "event": "email.replied",
  "data": {
    "activity_id": 1234,
    "company_id": 42,
    "contact_id": 88,
    "from_email": "john@smithpools.com",
    "subject": "Re: Quick question about your site",
    "preview": "[Reply] Re: Quick question — I'd be interested...",
    "received_at": "..."
  }
}

meeting.booked

Fires when iClosed confirms a real booking via the iClosed webhook. Includes the scheduled time when iClosed provides it.

{
  "event": "meeting.booked",
  "data": {
    "report_id": 17,
    "company_id": 42,
    "company_name": "Smith Pools",
    "booked_email": "john@smithpools.com",
    "invitee_name": "John Smith",
    "scheduled_at": "2026-05-12T15:00:00-07:00",
    "source": "iclosed"
  }
}

sequence.created

Fires when a new outreach sequence is enrolled on a contact. kind identifies which path triggered it: contact_outreach (manual Start Sequence button), pursue (Companies → Pursue), post_call (auto-generated from a call transcript), autopilot (Auto Pilot campaign).

{
  "event": "sequence.created",
  "data": {
    "contact_id": 88,
    "company_id": 42,
    "company_name": "Smith Pools",
    "contact_email": "john@smithpools.com",
    "step_count": 13,
    "kind": "pursue"
  }
}

deal.stage_changed

Fires whenever a Deal moves between stages (manual edit, kanban drag, snooze/wake, won/lost). from_stage and to_stage are the canonical stage names: in_sequence, prospecting, qualified, proposal, negotiation, closed_won, closed_lost, snoozed.

{
  "event": "deal.stage_changed",
  "data": {
    "deal_id": 91,
    "company_id": 42,
    "name": "Smith Pools — Pool Builder Package",
    "from_stage": "qualified",
    "to_stage": "proposal",
    "value": 4200,
    "probability": 50,
    "package": "pool_builder",
    "assigned_to": 3
  }
}

company.merged

Fires when an admin merges duplicate Company rows. Use to clean up downstream systems that referenced the merged-away IDs (any record pointing at merged_from_ids should be repointed to kept_id).

{
  "event": "company.merged",
  "data": {
    "kept_id": 42,
    "kept_name": "Smith Pools",
    "merged_from_ids": [89, 102],
    "merged_from_names": ["Smith Pools LLC", "Smith Pools - Las Vegas"],
    "repoint_counts": {
      "activities": 24, "contacts": 3, "deals": 2,
      "generated_emails": 18, "tasks": 5
    }
  }
}

company.deleted

Fires before a Company is hard-deleted (so the payload still has the row data). All child records cascade-delete on our side; if you mirror these companies in another system, this is your cue to delete them too.

{
  "event": "company.deleted",
  "data": {
    "id": 42,
    "name": "Smith Pools",
    "website": "smithpools.com",
    "domain": "smithpools.com",
    "city": "Las Vegas",
    "state": "NV"
  }
}

Errors & Limits

Error format

FastAPI standard:

{ "detail": "Invalid or revoked API key" }

Status codes

Limits (v1)

• Pagination: limit max 200 per request, offset-based
• Rate limit: none enforced; please be reasonable. We'll add per-key throttling if abuse appears.
• Webhook timeout: 10s per delivery attempt
• Custom fields: only keys matching active definitions are accepted; unknown keys silently dropped
• Body size: no enforced limit, but POSTs larger than 1MB will be rejected by nginx

Coming in v2

• Webhook retry queue (currently single-attempt)
• Per-key rate limiting
• Cursor-based pagination
• More events: sequence.completed, deal.stage_changed, company.updated
• Native Zapier app (currently you can use Zapier's generic Webhooks-by-Zapier integration)