Skip to main content
POST
/
contacts
/
lists
/
{listId}
/
entities
Add Contacts to 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_abc123def456ghi78",
    "ctc_xyz789uvw012rst34"
  ]
}
'
{
  "message": "Contacts added to list successfully",
  "addedCount": 2
}

Documentation Index

Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt

Use this file to discover all available pages before exploring further.

Adds existing contacts to a static contact list. Contacts already in the list are silently skipped — no duplicates are created.
You cannot add contacts to a dynamic list. Dynamic lists are auto-populated based on filter rules configured in the lemlist UI.

​
Typical workflow

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

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)

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

Body

application/json
​
contactIds
string[]
required

Array of contact IDs to add to the list (ctc_xxx format). Maximum 1,000 per request.

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

Response

Contacts added to list successfully

​
message
string
​
addedCount
integer

Number of contacts added to the list