> ## Documentation Index
> Fetch the complete documentation index at: https://help.retainful.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer overview

> Build on Retainful: REST API, custom events, webhooks, and storefront tracking.

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

<Columns cols={2}>
  <Card title="Sync contacts" icon="address-book" href="/developers/api/contacts">
    Create and update contact profiles from your own systems — signups, profile changes, consent updates.
  </Card>

  <Card title="Send custom events" icon="bolt" href="/developers/api/events">
    Track anything — bookings, renewals, quiz results — and use it to trigger automations and build segments.
  </Card>

  <Card title="Manage lists" icon="list" href="/developers/api/contact-groups">
    Add and remove contacts from lists programmatically.
  </Card>

  <Card title="Receive webhooks" icon="webhook" href="/developers/webhooks">
    Get an HTTP call to your endpoint when a contact reaches a webhook step in an automation.
  </Card>
</Columns>

## How the pieces fit

```text theme={null}
Your system ──POST /events──▶ Retainful ──triggers──▶ Automations ──▶ Email / WhatsApp
                                  │                        │
                                  ▼                        ▼
                              Segments ◀── profiles    Webhook step ──▶ your endpoint
```

1. **Authenticate** every request with an API key — see [Authentication](/developers/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](/automations/triggers#custom-events).
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](/developers/api/contact-groups) 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](/developers/errors).
* **Rate limits** — 10/second, 100/minute, 1,000/hour, counted per IP; see [Rate limits](/developers/rate-limits).

## Quick example

```bash Track an event theme={null}
curl -X POST "https://api.retainful.net/api/v1/events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $RETAINFUL_API_KEY" \
  -d '{
    "eventName": "Appointment Booked",
    "uniqueIdentifier": "booking_44812",
    "contact": { "email": "jane@example.com" },
    "eventData": {
      "service": "Consultation",
      "date": "2026-07-01"
    }
  }'
```

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](/developers/api/events#idempotency).

<Info>
  The base URL for API requests is shown alongside your API key when you create it in **Integrations**.
</Info>