Skip to main content
Lists (contact groups) organize your audience — see the merchant-side guide for the concepts. The API lets your systems manage membership: add a customer to “Active subscribers” when they start a plan, remove them when they cancel. All requests require authentication.

List your lists

GET /api/v1/contact-groups Returns the lists and segments in your organization, with their IDs. Use this to find the list ID you need for the add-contact call.
GET /api/v1/contact-groups/{id} returns a single list.

Add a contact to a list

POST /api/v1/contact-groups/{listId}/contacts Creates or updates the contact and adds them to the list, in one call. Returns 200 OK. The body is a flat contact object — the same field set as the Contacts API. Do not wrap it in a contact object and do not send an array; both are rejected with 400.
string
required
The contact’s email address. Required on this endpoint, even though the Contacts API accepts phone instead.
string
Max 100 characters.
string
Max 100 characters.
string
SUBSCRIBED, NON_SUBSCRIBED, or UNSUBSCRIBED. See the warning below — always set this explicitly.
string
7–20 characters.
string
Where the contact came from. Defaults to api.
Every other contact field is accepted here too.
Example request

Response

200 OK
action is created or updated, telling you whether the contact already existed. Note this endpoint returns a plain object — unlike the Contacts API, which returns a JSON:API envelope. A 404 means the list ID doesn’t exist. The contact may still have been created; it just isn’t in that list.
Always send email_opt_in explicitly on this endpoint. If you omit it, the result depends on whether the contact already existed: a brand-new contact is created as NON_SUBSCRIBED, but an existing contact is set to SUBSCRIBED. The same request body produces different consent outcomes depending on state you can’t see.

List membership as a trigger

Joining a list can trigger an automation — which makes this API a simple, robust way to start flows from your backend:
  1. Create a list like “Trial started” in the dashboard.
  2. Build a welcome/onboarding automation triggered by Subscribed to list → Trial started.
  3. From your backend, add users to the list when their trial begins.
The trigger fires once per contact per list. Adding someone who’s already a member won’t fire it again.
For richer use cases — where the triggering moment carries data you want in filters and emails — prefer custom events. Lists-as-triggers shine when the only fact that matters is membership itself.
Adding someone to a list does not make them marketable — their subscription status still governs whether marketing email reaches them. Manage consent through the email_opt_in field.

Contacts not showing up?

Contacts are written synchronously — if you got a success response with a contactUUID, the contact exists. If you can’t see it:
  1. Check action in the response. A response without a contact object means you’re not hitting this endpoint — verify the URL.
  2. Verify the list ID. A wrong ID returns 404; look it up with GET /api/v1/contact-groups.
  3. Match the API key to the organization you’re viewing in the dashboard. A key belongs to exactly one organization.
  4. Check email_opt_in. Contacts created as NON_SUBSCRIBED are hidden by the default subscription filters on the Members tab.
  5. Clear filters on the Members view, and hard-refresh — the dashboard caches client-side.