API Reference
Contact Lists API
Manage reusable contact lists for campaigns, imports, and operations.
Contact lists group contacts without duplicating the underlying contact records. API keys need contact_lists:read for reads and contact_lists:write for create, update, and delete operations.
Available Endpoints
/v1/contact-lists- List contact lists/v1/contact-lists- Create a contact list/v1/contact-lists/:id- Get a contact list/v1/contact-lists/:id- Update a contact list/v1/contact-lists/:id- Delete a contact listList Contact Lists
/v1/contact-listsRetrieves a paginated list of contact lists in the authenticated workspace.
Query Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of lists to return (1-100, default: 20) |
offset | integer | Number of lists to skip (default: 0) |
curl -X GET "https://www.nutalk.ai/v1/contact-lists?limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": [
{
"id": "list_abc123",
"name": "Q2 Prospects",
"description": "Imported prospect list",
"contact_count": 250,
"created_at": "2026-05-08T18:45:00.000Z",
"updated_at": "2026-05-08T18:45:00.000Z"
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}Create Contact List
/v1/contact-listsRequest Body
| Name | Type | Description |
|---|---|---|
nameRequired | string | Contact list name (1-200 characters) |
description | string | Internal list description (max 1000 characters) |
curl -X POST "https://www.nutalk.ai/v1/contact-lists" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Q2 Prospects", "description": "Imported prospect list"}'{
"success": true,
"data": {
"id": "list_abc123",
"name": "Q2 Prospects",
"description": "Imported prospect list",
"contact_count": 0,
"created_at": "2026-05-08T18:45:00.000Z",
"updated_at": "2026-05-08T18:45:00.000Z"
}
}Get Contact List
/v1/contact-lists/:idQuery Parameters
| Name | Type | Description |
|---|---|---|
include_members | boolean | Include a paginated sample of list members |
members_limit | integer | Number of members to return (1-100, default: 25) |
members_offset | integer | Number of members to skip (default: 0) |
curl -X GET "https://www.nutalk.ai/v1/contact-lists/list_abc123?include_members=true" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"id": "list_abc123",
"name": "Q2 Prospects",
"description": "Imported prospect list",
"contact_count": 250,
"members": {
"data": [],
"pagination": {
"total": 250,
"limit": 25,
"offset": 0,
"has_more": true
}
}
}
}Update Contact List
/v1/contact-lists/:idRequest Body
| Name | Type | Description |
|---|---|---|
name | string | New list name |
description | string | null | New description or null to clear it |
curl -X PATCH "https://www.nutalk.ai/v1/contact-lists/list_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Q2 Enterprise Prospects"}'{
"success": true,
"data": {
"id": "list_abc123",
"name": "Q2 Enterprise Prospects",
"description": "Imported prospect list",
"contact_count": 250
}
}Delete Contact List
/v1/contact-lists/:idcurl -X DELETE "https://www.nutalk.ai/v1/contact-lists/list_abc123" \ -H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"data": {
"id": "list_abc123",
"deleted": true
}
}Memberships Are Removed
Deleting a contact list removes the list and its memberships. Contact records remain available in the Contacts API.