Skip to main content
Version: 1.0.0

ProspectConnect Public API

Whitelabel-neutral public REST API for the platform. This is an additive facade over the internal services — the product frontend keeps using the internal API unchanged.

Conventions (apply to every endpoint):

  • Auth: OAuth 2.0 Bearer (Authorization: Bearer <token>). Per-tenant Personal Access Tokens (PAT) in v1; full auth-code + PKCE for marketplace apps. The token carries the tenant (business_id) and the user's role/permissions — the gateway enforces scope ∩ role.
  • Versioning: path /v1 (major) + a required Version: <YYYY-MM-DD> header (dated behavior contract).
  • IDs: opaque, type-prefixed strings (con_…, cmp_…, deal_…, task_…, note_…, act_…).
  • Pagination: cursor-based; one uniform envelope { data, meta: { cursor: { next, has_more }, total? } }. Search is POST /{resource}/search with { filters, search_text, order_by, sort_direction, limit, cursor }.
  • Errors: RFC 9457 application/problem+json with trace_id.
  • Dates: ISO-8601 / RFC 3339 UTC (2026-06-17T14:30:00Z); date-only fields YYYY-MM-DD.
  • Casing: snake_case JSON (matches internal storage; reduces mapping).
  • Methods: POST create, GET read, PATCH partial update, DELETE; Idempotency-Key honored on creates.
  • Rate limits: per-token; X-RateLimit-* response headers.

Wave 1 ships Contacts, Companies, Deals (+Pipelines), Tasks, Notes, and Activities — all detailed in this spec on the identical pattern. Later waves (engagement & scheduling, commerce, content/automation, reporting) extend the same conventions; once you've integrated Wave 1, the rest of the surface looks identical.

Authentication​

Authorization-code + PKCE for marketplace apps.

Security Scheme Type:

oauth2

OAuth Flow (authorizationCode):

Scopes:

  • contact.read: Read contacts and their sub-resources

  • contact.write: Create / update contacts and tags

  • contact.delete: Delete contacts

  • contact.all: Full contact access

  • company.read: Read companies

  • company.write: Create / update companies

  • company.delete: Delete companies

  • company.all: Full company access

  • deal.read: Read deals and pipelines

  • deal.write: Create / update deals (incl. stage changes)

  • deal.delete: Delete deals

  • deal.all: Full deal access

  • task.read: Read tasks

  • task.write: Create / update / complete tasks

  • task.delete: Delete tasks

  • task.all: Full task access

  • note.read: Read notes

  • note.write: Create / update / pin notes

  • note.delete: Delete notes

  • note.all: Full note access

  • activity.read: Read the activity timeline

  • activity.write: Log activities

  • activity.delete: Delete activities

  • activity.all: Full activity access