C10 - API & Webhooks

10.1 Getting your API key

Where to find it 12 integrations Your API key is visible on the Integrations page in PersistIQ settings. Sign in at https://persistiq.com/app, open Settings, and go to Integrations. Using the key API requests authenticate with your key — pass it with each request to the PersistIQ API. See the API documentation linked from the Integrations page for endpoints and parameters. Key hygiene - Never commit it to a repository — use environment variables or a secrets manager. - Never put it in client-side code — anything a browser can read is public. - Rotate if exposed. If a key leaks (a pasted log, a screenshot), treat it as compromised and rotate. - Scope access — give the key only to systems that need it. First request checklist 1. Copy the key from the Integrations page. 2. Store it securely on the system that will call the API. 3. Make a read-only request (e.g. list prospects) to verify authentication. 4. Build from there — see Core API endpoints.

10.2 Core API endpoints

Orienting first 12 integrations The authoritative, up-to-date endpoint reference is the PersistIQ API documentation (linked from the Integrations page). This article covers the shape of the API so you can plan an integration. The resources you'll use most - Prospects — create, read, update prospects; set custom field values; manage snippets. - Campaigns — list campaigns and their structure. - Campaign membership — add prospects to campaigns (the programmatic path to "start outreach on this list"). - Users / mailbox context — who owns what, for routing logic. Typical integration patterns 1. Lead router: form/tool → create prospect via API → add to campaign → follow-ups run. 2. List sync: data warehouse → nightly job → upsert prospects → attach to campaign. 3. Status mirror: webhook events → write outreach status back to your system of record. Rules of the road - Respect rate limits — batch operations where the API allows, back off on errors. - Make writes idempotent (check-before-create by email) — retries shouldn't duplicate prospects. - Don't add opted-out or bounced prospects to campaigns via API; the triggers will stop them, but you're wasting sends. [CONFIRM: exact endpoint list, parameters, and rate limits from the current API docs]

10.3 Webhook events

Webhooks vs the API 12 integrations The API pulls data when you ask. Webhooks push data the moment something happens. Real-time systems need both: webhooks for immediacy, API for full state. Event categories The events worth wiring up mirror the prospect lifecycle: - Replied — the highest-value event; route to Slack and the account owner. - Opted out — propagate the unsubscribe everywhere it matters. - Bounced — clean the address in downstream systems too. - Auto-reply — schedule follow-up for when the prospect returns. - Completed with no reply — trigger post-sequence workflow. Building a receiver 1. Expose an HTTPS endpoint. 2. Register it via the Integrations page / API documentation. 3. Acknowledge receipt fast (2xx) and queue processing. 4. Handle duplicates idempotently — retries are part of the deal. 5. Log raw payloads; you'll need them the first time an event "didn't arrive". [CONFIRM: exact event names, payload schema, and signature/verification scheme from the current API docs]

10.4 Common integration patterns

Pattern 1: The lead router 12 integrations Flow: website form / webinar / Inbound tool → middleware (Zapier, serverless function) → PersistIQ API creates prospect → adds to campaign. Watch for: deduplication by email before create; filling at least the Snippet field with something real; excluding existing opted-out contacts. Pattern 2: Reply-to-Slack Flow: webhook (replied) → function → Slack message with prospect link. Watch for: idempotency (retries duplicate alerts); include the prospect URL in the message so the SDR lands on the record in one click. Pattern 3: CRM status mirror Flow: webhook events (replied / opted out / bounced) → write status to your CRM (native Salesforce/Pipedrive/Copper sync, or API calls to something else). Watch for: mapping PersistIQ states to CRM stages deliberately — don't create a stage per event. Pattern 4: The analytics pipeline Flow: webhooks → queue → warehouse → BI tool. Watch for: store raw event payloads; derived tables can be rebuilt, raw events can't. Pattern 5: The nightly upsert Flow: source of truth (data warehouse, Sheets, Airtable) → scheduled job → API upsert prospects → attach to campaign. Watch for: making the job resumable; a failed 5,000-row sync shouldn't start from scratch or double-send. General rules - One system of record per data type; everything else syncs from it. - Log every API error with context — "409 on prospect create" is useless without the payload. - Test the failure paths, not just the happy path: what happens when the API is down during your nightly sync?