Skip to main content
POST
/
contacts
/
lists
/
{listId}
/
entities
Add or Remove Contacts in a List
curl --request POST \
  --url https://api.lemlist.com/api/contacts/lists/{listId}/entities \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contactIds": [
    "ctc_xxxxxxxxxxxxxxxxx",
    "ctc_yyyyyyyyyyyyyyyyy"
  ]
}
'
{ "message": "Contacts added to list successfully", "addedCount": 2, "alreadyInList": 0 }
Adds existing CRM contacts to a static contact list, or removes them when you set ?action=remove. The list must be a static contact list (clt_xxx); dynamic lists (auto-populated by filter rules) and company lists are rejected.
Removal uses POST ?action=remove, not DELETE. A DELETE request body is dropped by our stack, so DELETE on this path is not supported and returns 405 Method Not Allowed.
Removing a contact from a list only affects list membership — it does not delete the contact from your CRM.

​
Add vs remove

ActionRequestResult
AddPOST with { "contactIds": [...] }Contacts are added. Those already in the list are silently skipped (counted in alreadyInList).
RemovePOST ?action=remove with { "contactIds": [...] }Contacts are removed. Those not in the list are silently skipped (removedCount reflects associations actually removed).

​
Typical workflow

  1. Find or create a list — use GET /contacts/lists to find an existing static list, or POST /contacts/lists to create one (clt_xxx).
  2. Find contacts — use GET /contacts with search, email, or listId to get contact IDs (ctc_xxx).
  3. Add or remove — call this endpoint with the contact IDs and list ID. Up to 1,000 contacts per request.

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

​
listId
string
required

The unique identifier of the contact list (clt_xxx format). Must be a static contact list.

Pattern: ^clt_[a-zA-Z0-9]+$

Query Parameters

​
action
enum<string>

Omit to add the contacts to the list. Set to remove to remove them from the list.

Available options:
remove

Body

application/json
​
contactIds
string[]
required

Array of contact IDs (ctc_xxx format) to add to or remove from the list. Required, non-empty, maximum 1,000 per request.

Required array length: 1 - 1000 elements
Pattern: ^ctc_[a-zA-Z0-9]+$

Response

Contacts added to or removed from the list successfully. The response body depends on action.

​
message
string
​
addedCount
integer

Number of contacts added to the list (add only).

​
alreadyInList
integer

Number of contacts that were already in the list and therefore skipped (add only).

​
removedCount
integer

Number of list associations actually removed (remove only). Contacts that were not in the list are not counted.