Marketing Lists API

The Marketing Lists API manages audience lists and their membership. Lists are a reusable audience for campaigns, and adding members can trigger sequence auto-enrollment.

REST API. Authenticated with Authorization: Bearer rk_live_…. Successful responses are wrapped in { "data": … }.

Required Scopes

List Object

{
  id: string;
  organization_id: string;
  name: string;
  description?: string | null;
  opt_in_process: 'single' | 'double';
  status: 'active' | 'archived';
  member_count: number;
  created_at: string;
}

List / Get / Create / Update / Delete

GET /api/v1/marketing-lists — query params status, limit, offset. Scope: lists:read.

GET /api/v1/marketing-lists/:id — single list. Scope: lists:read.

POST /api/v1/marketing-lists — body { name, description?, opt_in_process? }. Returns 201. A duplicate name returns 409. Scope: lists:write.

PATCH /api/v1/marketing-lists/:id — update name, description, opt_in_process, status. Scope: lists:write.

DELETE /api/v1/marketing-lists/:id — delete (cascades memberships). Returns 204. Scope: lists:write.

curl -X POST "https://crm.switchlabs.dev/api/v1/marketing-lists" \
  -H "Authorization: Bearer rk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "name": "Tech journalists" }'

List Members

GET /api/v1/marketing-lists/:id/members

Scope: lists:read

Query params: status (subscribed|unsubscribed|pending), limit, offset. Each row embeds a customer summary.

Add Members

POST /api/v1/marketing-lists/:id/members

Scope: lists:write

Add existing contacts (by UUID) to the list. Contact ids that don't belong to your org are skipped. Adding members fires any list-triggered sequence enrollment (a sequence whose trigger_config.list_id matches this list).

Body:

{
  customer_ids: string[];   // 1-1000 UUIDs
  source?: 'manual' | 'import' | 'api' | 'form' | 'migration';  // default "api"
}

curl -X POST "https://crm.switchlabs.dev/api/v1/marketing-lists/LIST_ID/members" \
  -H "Authorization: Bearer rk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "customer_ids": ["uuid-1", "uuid-2"] }'
# -> { "data": { "added": 2, "skipped": 0 } }

Remove / Unsubscribe Members

DELETE /api/v1/marketing-lists/:id/members

Scope: lists:write

Body { "customer_ids": [ … ] }. By default the membership rows are deleted. Pass ?mode=unsubscribe to instead keep the rows and mark them unsubscribed (preserving suppression history).

curl -X DELETE "https://crm.switchlabs.dev/api/v1/marketing-lists/LIST_ID/members?mode=unsubscribe" \
  -H "Authorization: Bearer rk_live_xxx" -H "Content-Type: application/json" \
  -d '{ "customer_ids": ["uuid-1"] }'

See also: Campaigns · Sequences · Customers