Public API · v1

Pitchdar API reference

Score any business from one POST. List your own scored leads. Register outbound webhooks so your stack reacts when a hot prospect crosses your fit threshold. JSON over HTTPS, bearer-token auth, no SDK required.

Authentication

Every request must send Authorization: Bearer pk_live_… with an org-scoped API key. Create one at /app/settings/api-keys. The full secret is shown once on creation. Keys are tied to one workspace and never expire — revoke them when a contractor leaves.

Scope read_write: all endpoints.
Scope read: GET /leads and GET /webhooks only.

Rate limits vary by plan: Trial 60/min, Starter 120/min, Pro 600/min, Agency 1,200/min. Exceeded calls return 429 + Retry-After.

POST /api/v1/score

Score a business 1-100 for fit. Use the niche slug from /leads for best results. Setting offer sharpens the pitch angle.

curl -X POST https://www.pitchdar.com/api/v1/score \
  -H "Authorization: Bearer $PITCHDAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Bondi Brew Coffee Bar",
    "address": "Sydney NSW 2026",
    "niche": "cafe",
    "rating": 4.6,
    "reviewCount": 412,
    "website": "https://bondibrew.example",
    "offer": "Direct ordering site to bypass UberEats"
  }'

200 response:

{
  "fitScore": 88,
  "pitchAngle": "Add 1-click ordering on existing site",
  "topPains": ["No native ordering", "High Uber commission", "Slow site on mobile"],
  "source": "claude"
}

If fitScore >= 80, the org's registered webhooks receive a lead.scored.high event.

GET /api/v1/leads

Paginated list of the org's leads. Filter by minScore or status; paginate via cursor.

curl https://www.pitchdar.com/api/v1/leads?minScore=80&limit=20 \
  -H "Authorization: Bearer $PITCHDAR_API_KEY"

{
  "data": [
    {
      "id": "ld_…",
      "name": "Bondi Brew Coffee Bar",
      "category": "cafe",
      "city": "Sydney",
      "country": "AU",
      "website": "https://…",
      "email": "owner@…",
      "phone": "+61…",
      "rating": 4.6,
      "reviewCount": 412,
      "fitScore": 88,
      "status": "new",
      "createdAt": "2026-06-05T22:00:00.000Z"
    }
  ],
  "nextCursor": "1748131200000"
}

POST /api/v1/webhooks

curl -X POST https://www.pitchdar.com/api/v1/webhooks \
  -H "Authorization: Bearer $PITCHDAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.your-app.com/pitchdar",
    "events": ["lead.scored.high"],
    "description": "Production CRM sync"
  }'

{
  "id": "wh_…",
  "url": "https://api.your-app.com/pitchdar",
  "secret": "whsec_…",
  "events": ["lead.scored.high"],
  "signingHeader": "X-Pitchdar-Signature",
  "signingScheme": "t=<unix-seconds>,v1=<hex sha256 of `<ts>.<body>`>"
}

Verify signatures by computing HMAC_SHA256(secret, "<t>.<body>") and comparing in constant time. Reject deliveries whose timestamp is > 5 minutes off your clock.

Events

lead.scored.high — fires from POST /score when fitScore ≥ 80.
lead.created — when a lead is added to the workspace from any source.
subscription.created / subscription.canceled — billing lifecycle.
test.ping — manual test from the dashboard.

Errors

400 { "error": "invalid_json" }
401 { "error": "missing_or_invalid_api_key" }
403 { "error": "plan_lacks_api_access" } — upgrade to Pro+
403 { "error": "key_scope_insufficient" } — write op with read scope
429 { "error": "rate_limit_exceeded" } — back off per Retry-After
500 { "error": "internal_error" }

Need a Zapier or HubSpot template?

Email api@pitchdar.com with what you want to build. We'll ship sample code (and often, a published Zap template) within 24h.