Lists & Segments
Overview
Contact Lists are static, named collections — add contacts manually via the API or dashboard. Segments are named groups that you can populate programmatically. Both can be used as audience targets when creating outreach campaigns.
Contact Lists
The ContactList object
{
"id": 3,
"name": "Q1 Leads",
"status": 1,
"contacts_count": 87,
"created_at": "2026-01-05T10:00:00.000000Z"
}
List all lists
GET /api/v1/contacts/lists
Returns all contact lists with member counts.
curl https://dashboard.skylightchat.com/api/v1/contacts/lists \
-H "X-Api-Key: ••••••••••••"
Create a list
POST /api/v1/contacts/lists
| Field | Type | Required |
|---|---|---|
name | string | ✓ |
curl -X POST https://dashboard.skylightchat.com/api/v1/contacts/lists \
-H "X-Api-Key: ••••••••••••" \
-H "Content-Type: application/json" \
-d '{ "name": "Spring Campaign Targets" }'
Get a list
GET /api/v1/contacts/lists/{id}
Update a list
PUT /api/v1/contacts/lists/{id}
| Field | Type | Notes |
|---|---|---|
name | string | New name |
status | integer | 1 = active, 0 = inactive |
Delete a list
DELETE /api/v1/contacts/lists/{id}
Deletes the list and removes all contact memberships. Returns 204 No Content.
Get list members
GET /api/v1/contacts/lists/{id}/members
Returns a paginated list of contacts in the list.
| Parameter | Type | Description |
|---|---|---|
per_page | integer | Results per page (max 100) |
{
"success": true,
"data": [
{ "id": 42, "name": "Noura Al-Otaibi", "phone": "+966501234567", "type": "whatsapp" }
],
"meta": { "total": 87, "current_page": 1, "per_page": 25, "last_page": 4 }
}
Add a contact to a list
POST /api/v1/contacts/{id}/lists
| Field | Type | Required |
|---|---|---|
list_id | integer | ✓ |
This is idempotent — adding a contact already in the list has no effect.
Remove a contact from a list
DELETE /api/v1/contacts/{id}/lists/{list_id}
Returns 204 No Content.
Segments
Segments follow the same pattern as lists but are designed for rule-based grouping. You define the name and populate membership via the API.
The Segment object
{
"id": 2,
"title": "High Value Customers",
"status": 1,
"created_at": "2026-01-10T08:00:00.000000Z"
}
List all segments
GET /api/v1/contacts/segments
Create a segment
POST /api/v1/contacts/segments
| Field | Type | Required |
|---|---|---|
title | string | ✓ |
Update a segment
PUT /api/v1/contacts/segments/{id}
| Field | Type |
|---|---|
title | string |
status | integer |
Delete a segment
DELETE /api/v1/contacts/segments/{id}
Returns 204 No Content.
Get segment members
GET /api/v1/contacts/segments/{id}/members
Returns a paginated list of contacts in the segment. Same response shape as Get list members.
| Parameter | Type | Description |
|---|---|---|
per_page | integer | Results per page (max 100) |
{
"success": true,
"data": [
{ "id": 42, "name": "Noura Al-Otaibi", "phone": "+966501234567", "email": "noura@example.com", "type": "whatsapp" }
],
"meta": { "total": 12, "current_page": 1, "per_page": 25, "last_page": 1 }
}
Add a contact to a segment
POST /api/v1/contacts/{id}/segments
| Field | Type | Required |
|---|---|---|
segment_id | integer | ✓ |
Remove a contact from a segment
DELETE /api/v1/contacts/{id}/segments/{segment_id}
Returns 204 No Content.