API Reference
Contacts
Create, retrieve, update, delete, and organize your contacts.
The Contact object
{
"id": 42,
"name": "Sarah Johnson",
"email": "sarah@example.com",
"phone": "+14155551234",
"type": "whatsapp",
"status": "active",
"blacklisted": false,
"tags": ["vip", "newsletter"],
"last_message_at": "2026-03-04T10:00:00.000000Z",
"created_at": "2026-01-15T08:22:00.000000Z",
"updated_at": "2026-03-04T10:00:00.000000Z"
}
| Field | Type | Description |
|---|---|---|
id | integer | Unique contact identifier |
name | string | Full name |
email | string|null | Email address |
phone | string|null | Phone number (E.164 format) |
type | string | Channel: whatsapp, telegram, instagram |
status | string | active or inactive |
blacklisted | boolean | Whether the contact is blacklisted |
tags | array | Array of tag strings |
last_message_at | string|null | ISO 8601 timestamp of last message |
created_at | string | ISO 8601 creation timestamp |
updated_at | string | ISO 8601 last-update timestamp |
List contacts
GET /api/v1/contacts
Returns a paginated list of your contacts.
Query parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
per_page | integer | Results per page (default: 15, max: 100) |
search | string | Search by name, email, or phone |
type | string | Filter by channel: whatsapp, telegram, instagram |
blacklisted | boolean | Filter blacklisted contacts (true / false) |
tag | string | Filter by tag |
Example
curl "https://dashboard.skylightchat.com/api/v1/contacts?search=sarah&type=whatsapp" \
-H "Authorization: Bearer sk_live_••••••••••••"
Response
{
"success": true,
"data": [
{
"id": 42,
"name": "Sarah Johnson",
"phone": "+14155551234",
"type": "whatsapp",
"blacklisted": false,
"tags": ["vip"]
}
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 15,
"total": 1
}
}
Create a contact
POST /api/v1/contacts
Request body
{
"name": "Sarah Johnson",
"phone": "+14155551234",
"email": "sarah@example.com",
"type": "whatsapp",
"tags": ["vip", "newsletter"]
}
| Field | Required | Description |
|---|---|---|
name | ✓ | Full name |
type | ✓ | Channel: whatsapp, telegram, instagram |
phone | conditional | Required for whatsapp and telegram |
email | — | Email address |
tags | — | Array of tag strings |
Example
curl -X POST https://dashboard.skylightchat.com/api/v1/contacts \
-H "Authorization: Bearer sk_live_••••••••••••" \
-H "Content-Type: application/json" \
-d '{"name":"Sarah Johnson","phone":"+14155551234","type":"whatsapp"}'
Response 201 Created
{
"success": true,
"data": {
"id": 42,
"name": "Sarah Johnson",
"phone": "+14155551234",
"type": "whatsapp",
"blacklisted": false,
"tags": [],
"created_at": "2026-03-04T12:00:00.000000Z"
},
"message": "Contact created successfully."
}
Get a contact
GET /api/v1/contacts/{id}
curl https://dashboard.skylightchat.com/api/v1/contacts/42 \
-H "Authorization: Bearer sk_live_••••••••••••"
Response
{
"success": true,
"data": {
"id": 42,
"name": "Sarah Johnson",
"phone": "+14155551234",
"email": "sarah@example.com",
"type": "whatsapp",
"status": "active",
"blacklisted": false,
"tags": ["vip"],
"created_at": "2026-01-15T08:22:00.000000Z",
"updated_at": "2026-03-04T10:00:00.000000Z"
}
}
Update a contact
PUT /api/v1/contacts/{id}
All fields are optional. Only the provided fields are updated.
curl -X PUT https://dashboard.skylightchat.com/api/v1/contacts/42 \
-H "Authorization: Bearer sk_live_••••••••••••" \
-H "Content-Type: application/json" \
-d '{"name":"Sarah M. Johnson","tags":["vip","priority"]}'
Response 200 OK
{
"success": true,
"data": { "id": 42, "name": "Sarah M. Johnson", "tags": ["vip","priority"] },
"message": "Contact updated successfully."
}
Delete a contact
DELETE /api/v1/contacts/{id}
curl -X DELETE https://dashboard.skylightchat.com/api/v1/contacts/42 \
-H "Authorization: Bearer sk_live_••••••••••••"
Response 204 No Content
No response body.
Blacklist a contact
POST /api/v1/contacts/{id}/blacklist
Toggles the blacklisted state of the contact.
curl -X POST https://dashboard.skylightchat.com/api/v1/contacts/42/blacklist \
-H "Authorization: Bearer sk_live_••••••••••••"
Response
{
"success": true,
"data": { "id": 42, "blacklisted": true },
"message": "Contact blacklisted successfully."
}
Contact notes
List notes
GET /api/v1/contacts/{id}/notes
Add a note
POST /api/v1/contacts/{id}/notes
{ "content": "Called today — interested in Pro plan." }
Contact lists & segments
Add to a list
POST /api/v1/contacts/{id}/lists
{ "list_id": 5 }
Add to a segment
POST /api/v1/contacts/{id}/segments
{ "segment_id": 3 }