Skip to main content
The Retainful API lets your systems talk to Retainful directly — create contacts, send custom events that trigger automations, and manage list membership. If you run a custom storefront, a subscription service, or any backend with customer activity, this is how you plug it in.

​
What you can build

Sync contacts

Create and update contact profiles from your own systems — signups, profile changes, consent updates.

Send custom events

Track anything — bookings, renewals, quiz results — and use it to trigger automations and build segments.

Manage lists

Add and remove contacts from lists programmatically.

Receive webhooks

Get an HTTP call to your endpoint when a contact reaches a webhook step in an automation.

​
How the pieces fit

  1. Authenticate every request with an API key — see Authentication.
  2. Create contacts or let events create them implicitly.
  3. Send events as things happen. Events appear on contact timelines, are available to segments, and can trigger automations.
  4. Receive webhooks from automation flows to close the loop into your own systems.

​
Conventions

  • Format — JSON in, JSON out. Most responses use a JSON:API-style envelope: a data object with type, id, attributes, and links. Adding a contact to a list is the exception and returns a plain object.
  • Field names — snake_case (first_name, not firstName). Unrecognized fields are rejected with 400 rather than ignored.
  • IDs — resources are identified by stable unique IDs; contacts can also carry your own external_id.
  • Errors — standard HTTP status codes with a JSON body; see Errors.
  • Rate limits — 10/second, 100/minute, 1,000/hour, counted per IP; see Rate limits.

​
Quick example

Track an event
That single call creates the contact if needed, records the event on her timeline, and fires any automation triggered by Appointment Booked. The uniqueIdentifier makes it safe to retry — see Idempotency.
The base URL for API requests is shown alongside your API key when you create it in Integrations.