Contact lists API
A contact list groups contacts for campaigns. A campaign can use a list as its default list: contacts added to the list are enrolled in it, and an active campaign starts contacting them.
contact_lists:readcontact_lists:write7 endpointsShow
/v1/contact-listsList contact lists
Lists contact lists, newest first, with their member counts.
contact_lists:readQuery parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/contact-lists?limit=10" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"name": "Q2 Prospects",
"description": "Imported prospect list",
"contact_count": 2,
"created_at": "2026-10-02T02:25:25.707964+00:00",
"updated_at": "2026-10-02T02:25:25.707964+00:00"
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}/v1/contact-listsCreate a contact list
Creates an empty list. Add members with POST /v1/contact-lists/{id}/members or a contact import (POST /v1/contact-imports); in the dashboard, CRM syncs and campaign imports fill lists too.
contact_lists:writeRequest body
namestring · 1–200 charactersrequiredList name.
descriptionstring · up to 1,000What the list holds.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/contact-lists \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Q2 Prospects",
"description": "Imported prospect list"
}'{
"success": true,
"data": {
"id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"name": "Q2 Prospects",
"description": "Imported prospect list",
"contact_count": 0,
"created_at": "2026-10-02T02:25:25.707964+00:00",
"updated_at": "2026-10-02T02:25:25.707964+00:00"
}
}/v1/contact-lists/:idGet a contact list
Returns one list. With include_members=true it also returns a page of its members (newest first) with their contact details.
contact_lists:readMembers come with their name, phone and email, so a key with contact_lists:read can read those contacts even without contacts:read.
Path parameters
iduuidrequiredThe contact list id.
Query parameters
include_membersbooleanAlso return a page of members. Default: false.
members_limitinteger · 1–100Members per page. Default: 25.
members_offsetinteger · at least 0Members to skip. Default: 0.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).404not_foundNo contact list with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/contact-lists/d2406224-509f-4177-9a5a-b50bee1e7590?include_members=true" \ -H "Authorization: Bearer $NUTALK_API_KEY"
members when requested{
"success": true,
"data": {
"id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"name": "Q2 Prospects",
"description": "Imported prospect list",
"contact_count": 2,
"created_at": "2026-10-02T02:25:25.707964+00:00",
"updated_at": "2026-10-02T02:25:25.707964+00:00",
"members": {
"data": [
{
"id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
"added_at": "2026-10-02T02:30:00.000000+00:00",
"contacts": {
"id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"phone_number": "+14155551234",
"first_name": "Jane",
"last_name": "Smith",
"display_name": null,
"email": "jane@example.com",
"company": "Tech Startup",
"tags": [
"prospect"
],
"created_at": "2026-10-02T02:25:06.947918+00:00",
"updated_at": "2026-10-02T02:25:06.947918+00:00"
}
}
],
"pagination": {
"total": 2,
"limit": 25,
"offset": 0,
"has_more": false
}
}
}
}/v1/contact-lists/:idUpdate a contact list
Renames a list or changes its description (null clears it).
contact_lists:writeCan wait for approvalPath parameters
iduuidrequiredThe contact list id.
Request body
namestring · 1–200 charactersNew name.
descriptionstring | null · up to 1,000New description, or null.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorNo field to change was sent.404not_foundNo contact list with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/contact-lists/d2406224-509f-4177-9a5a-b50bee1e7590 \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Q2 Enterprise Prospects"
}'{
"success": true,
"data": {
"id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"name": "Q2 Enterprise Prospects",
"description": "Imported prospect list",
"contact_count": 2,
"created_at": "2026-10-02T02:25:25.707964+00:00",
"updated_at": "2026-10-02T02:25:26.692147+00:00"
}
}/v1/contact-lists/:idDelete a contact list
Deletes the list and its memberships. The contacts themselves stay; a campaign that used it as its default list keeps running without one. The enrollments the list created in its campaigns are removed while they have not produced an outcome yet, so when the list is linked to a campaign the key also needs campaigns:write.
contact_lists:writeWaits for approvalPath parameters
iduuidrequiredThe contact list id.
Unless its key was set not to wait, nothing is removed yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
403forbiddenThe list is linked to a campaign and the key lacks campaigns:write (details.required_scope).404not_foundNo contact list with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X DELETE https://www.nutalk.ai/v1/contact-lists/d2406224-509f-4177-9a5a-b50bee1e7590 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"deleted": true
}
}/v1/contact-lists/:id/membersAdd contacts to a list
Adds existing contacts of your workspace to the list (create them first with POST /v1/contacts). A contact already on the list is left as it is, and an id that is not one of your contacts is reported in not_found, never added. Adding a contact to a list that an outbound campaign uses enrolls it in that campaign, as in the dashboard: an active campaign starts contacting it. So when the list feeds an outbound campaign (draft, paused or active), the key also needs campaigns:write, the scope that enrolls contacts.
contact_lists:writeDo-not-contact contacts join the list but are never enrolled in its campaigns.
Placing contacts on a list used by an active campaign reaches real people and spends credits: confirm with the user first.
Path parameters
iduuidrequiredThe contact list id.
Request body
contact_idsuuid[] · 1–500 itemsrequiredContacts to add, 1 to 500 ids.
To create contacts and enroll them in a campaign in one call, use POST /v1/campaigns/:id/contacts/import.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorAn entry of contact_ids is not a UUID.403forbiddenThe list feeds an outbound campaign and the key lacks campaigns:write (details.required_scope).404not_foundNo contact list with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/contact-lists/d2406224-509f-4177-9a5a-b50bee1e7590/members \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_ids": [
"9595b646-ab97-4485-b1b8-e8b58dfcdd19"
]
}'{
"success": true,
"data": {
"list_id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"added": 1,
"already_members": 0,
"not_found": [],
"contact_count": 3
}
}/v1/contact-lists/:id/members/:contact_idRemove a contact from a list
Removes one contact from the list; the contact itself stays. The enrollments this list created in its campaigns are removed while they have not produced an outcome yet; calls already made and their outcomes stay. When the list is linked to a campaign, the key also needs campaigns:write.
contact_lists:writeWaits for approvalPath parameters
iduuidrequiredThe contact list id.
contact_iduuidrequiredThe contact id.
Unless its key was set not to wait, nothing is removed yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
403forbiddenThe list is linked to a campaign and the key lacks campaigns:write (details.required_scope).404not_foundNo contact list with this id in your workspace (ids of other workspaces answer the same).404not_foundThe contact is not on this list.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X DELETE https://www.nutalk.ai/v1/contact-lists/d2406224-509f-4177-9a5a-b50bee1e7590/members/9595b646-ab97-4485-b1b8-e8b58dfcdd19 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"list_id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"contact_id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"removed": true
}
}