Skip to main content
Contact lists are static groups you manually curate. Use them to target specific audiences in email campaigns.

​
Authentication

All endpoints require:
  • Authorization: Bearer YOUR_API_KEY
  • X-Project-ID: YOUR_PROJECT_ID (or encoded in the API key)

​
Endpoints

MethodPathDescription
GET/api/v1/contacts/listsList all contact lists
POST/api/v1/contacts/listsCreate a list
GET/api/v1/contacts/lists/:idGet a single list
PATCH/api/v1/contacts/lists/:idUpdate a list
DELETE/api/v1/contacts/lists/:idDelete a list
GET/api/v1/contacts/lists/:id/membersGet list members
POST/api/v1/contacts/lists/:id/membersAdd a contact to a list
DELETE/api/v1/contacts/lists/:id/membersRemove a contact from a list

​
List All Contact Lists

GET https://api.usegately.com/api/v1/contacts/lists
SDK
const lists = await crm.listContactLists()
Response 
[
  {
    "id": "list-uuid",
    "project_id": "proj-uuid",
    "name": "Newsletter Subscribers",
    "description": "Monthly newsletter opt-ins",
    "created_at": "2025-01-01T00:00:00.000Z"
  }
]

​
Create a List

POST https://api.usegately.com/api/v1/contacts/lists
Body 
{ "name": "Newsletter Subscribers", "description": "Monthly newsletter opt-ins" }
SDK
const list = await crm.createContactList({
  name: 'Newsletter Subscribers',
  description: 'Monthly newsletter opt-ins',
})

​
Update a List

PATCH https://api.usegately.com/api/v1/contacts/lists/LIST_ID
SDK
await crm.updateContactList('LIST_ID', { name: 'Weekly Newsletter' })

​
Delete a List

Deletes the list. Contacts are not deleted. 
DELETE https://api.usegately.com/api/v1/contacts/lists/LIST_ID
SDK
await crm.deleteContactList('LIST_ID')

​
Get List Members

GET https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members?page=1&limit=100
SDK
const members = await crm.getListMembers('LIST_ID', { page: 1, limit: 100 })
Response 
[
  {
    "contact_id": "contact-uuid",
    "list_id": "list-uuid",
    "added_at": "2025-03-01T10:00:00.000Z",
    "crm_contacts": { "id": "contact-uuid", "name": "Jane Smith", "email": "jane@example.com" }
  }
]

​
Add Contact to List

POST https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members
Body 
{ "contact_id": "CONTACT_ID" }
SDK
await crm.addContactToList('LIST_ID', 'CONTACT_ID')

​
Remove Contact from List

DELETE https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members?contact_id=CONTACT_ID
SDK
await crm.removeContactFromList('LIST_ID', 'CONTACT_ID')

​
TypeScript Type

interface ContactList {
  id: string
  project_id: string
  name: string
  description?: string | null
  created_at: string
  updated_at?: string
}