Lists

Endpoints

GET /v1/lists
GET /v1/lists/:id
POST /v1/lists
PATCH /v1/lists/:id
DELETE /v1/lists/:id
GET /v1/lists/:list_id/memberships
POST /v1/lists/:list_id/memberships
DELETE /v1/lists/:list_id/memberships

INFO

GET endpoints are available for all API users. However, POST, PATCH, and DELETE endpoints are only available if you are using the API as your sync source. If you are using a sync source other than the API to sync your employee data to Workshop, you can only use the GET endpoints.

List lists

GET /v1/lists

Returns a page of lists in reverse chronological order (newest created_at first).

Parameters

Name	Optional	Default	Description	Options
Pagination parameters			See pagination for more information.

Returns

A page of list objects. See Retrieve a list for more information on the list object.

Example response

json

{
  "object": "array",
  "has_more": true,
  "next": "/v1/lists?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "list",
      "id": "3d4e06a3-544b-4cc7-924e-e077ef133cf6",
      "external_id": "XYZ-098",
      "title": "All Employees",
      "email_address": "all-employees@example.com",
      "list_type": "standard",
      "list_source": "api",
      "memberships_count": 100,
      "creator_id": "a8f7c92d-1234-4abc-9def-0123456789ab",
      "description": "All active employees across the company",
      "created_at": "2025-08-12T14:30:00.000Z",
      "urls": {
        "memberships": "/v1/lists/3d4e06a3-544b-4cc7-924e-e077ef133cf6/memberships",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

Retrieve a list

GET /v1/lists/:id

Gets the details of a single list.

Parameters

Name	Optional	Type	Description
id	required	string	The ID of the list to retrieve.
external	optional	boolean	If lookup is done by `external_id` instead of `id`. Defaults to `false` (lookup by `id`).

INFO

You can only retrieve a list by external_id that is synced through the API. If you are using a sync source other than the API, a request with the external parameter will return a 404 error.

If the external flag is set, the system searches for a list whose external_id (instead of id) matches the id request parameter. You can supply the external parameter in the payload or as a query parameter like:

GET /v1/lists/:id?external

Returns

A list object, which contains the list's id, external_id, title, email_address, list_type, list_source, memberships_count, creator_id, description, created_at, and urls. The urls object contains only the key memberships, which is the endpoint for the list's memberships.

Example response

json

{
  "object": "list",
  "id": "3d4e06a3-544b-4cc7-924e-e077ef133cf6",
  "external_id": "XYZ-098",
  "title": "All Employees",
  "email_address": "all-employees@example.com",
  "list_type": "standard",
  "list_source": "api",
  "memberships_count": 100,
  "creator_id": "a8f7c92d-1234-4abc-9def-0123456789ab",
  "description": "All active employees across the company",
  "created_at": "2025-08-12T14:30:00.000Z",
  "urls": {
    "memberships": "/v1/lists/3d4e06a3-544b-4cc7-924e-e077ef133cf6/memberships"
  }
}

Create a list

POST /v1/lists

Creates a new list.

Parameters

Name	Optional	Type	Description
external_id	required	string	A unique identifier from your system for the list.
title	required	string	The title of the list.
email_address	optional	string	The email address of the list.
list_type	optional	string	The type of list. Must be one of `standard`, `location`, `department`, or `team`. Defaults to `standard`.
creator_id	optional	string	The ID of a user in your company to set as the list's creator.
description	optional	string	A free-form description for the list.

Example payload

json

{
  "external_id": "XYZ-098",
  "title": "All Employees",
  "email_address": "all-employees@example.com",
  "list_type": "standard",
  "creator_id": "a8f7c92d-1234-4abc-9def-0123456789ab",
  "description": "All active employees across the company"
}

Returns

The newly created list object and a 201 status code if successful. The response is the same shape as the object returned from Retrieve a list.

Example responses

Success response (201)

json

{
  "object": "list",
  "id": "3d4e06a3-544b-4cc7-924e-e077ef133cf6",
  "external_id": "XYZ-098",
  "title": "All Employees",
  "email_address": "all-employees@example.com",
  "list_type": "standard",
  "list_source": "api",
  "memberships_count": 0,
  "creator_id": "a8f7c92d-1234-4abc-9def-0123456789ab",
  "description": "All active employees across the company",
  "created_at": "2025-08-12T14:30:00.000Z",
  "urls": {
    "memberships": "/v1/lists/3d4e06a3-544b-4cc7-924e-e077ef133cf6/memberships"
  }
}

Error response (409)

json

{
  "error": "List with external_id XYZ-098 already exists"
}

Error response (422)

json

{
  "error": {
    "title": ["is missing"],
    "email_address": ["is in invalid format"],
    "creator_id": ["must be a user id in this company"]
  }
}

Errors

Code	Description
409	List with the same external_id already exists
422	Invalid request, missing required parameters or supplied parameters are invalid

Update a list

PATCH /v1/lists/:id

Updates a list.

Parameters

Name	Optional	Type	Description
id	required	string	The ID of the list to update.
external	optional	boolean	If lookup is done by `external_id` instead of `id`. Defaults to `false` (lookup by `id`).
external_id	optional	string	A unique identifier from your system for the list.
title	optional	string	The title of the list.
email_address	optional	string	The email address of the list.
list_type	optional	string	The type of list. Must be one of `standard`, `location`, `department`, or `team`.
creator_id	optional	string	The ID of a user in your company to set as the list's creator. Supply `null` to clear.
description	optional	string	A free-form description for the list. Supply `null` to clear.

If the external flag is set, the system searches for a list whose external_id (instead of id) matches the id request parameter. This differs from the external_id request parameter, which is used to set the external_id of a list.

If you do not supply a parameter, its value will remain unchanged. To clear creator_id or description for a list, supply null as the value.

Example payload

json

{
  "title": "Sales Department",
  "email_address": "sales-department@example.com",
  "list_type": "department",
  "creator_id": "a8f7c92d-1234-4abc-9def-0123456789ab",
  "description": "Everyone on the sales team"
}

Returns

A success message and a 200 status code if successful.

Example responses

Success response (200)

json

{
  "message": "List updated successfully"
}

Error response (404)

json

{
  "error": "List not found"
}

Error response (422)

json

{
  "error": {
    "email_address": ["is in invalid format"]
  }
}

Errors

Code	Description
404	List with the given ID was not found.
422	Invalid request, supplied parameters did not pass validation.

Delete a list

DELETE /v1/lists/:id

Deletes a list.

Parameters

Name	Optional	Type	Description
id	required	string	The ID of the list to delete.
external	optional	boolean	If lookup is done by `external_id` instead of `id`. Defaults to `false` (lookup by `id`).

If the external flag is set, the system searches for a list whose external_id (instead of id) matches the id request parameter.

Returns

A success message and a 200 status code if successful.

Example response

json

{
  "message": "List deleted successfully"
}

Errors

Code	Description
404	List with the given ID was not found.

List Memberships

List list memberships

GET /v1/lists/:list_id/memberships

Returns a page of list memberships.

Parameters

Name	Optional	Type	Description
list_id	required	string	The ID of the list to fetch memberships for.
external_list	optional	boolean	If the list lookup is done by `external_id` instead of `id`. Defaults to `false` (lookup by `id`).
Pagination parameters			See pagination for more information.

If the external_list flag is set, the system searches for a list whose external_id (instead of id) matches the list_id request parameter. You can supply the external_list parameter in the payload or as a query parameter like:

GET /v1/lists/:list_id/memberships?external_list

Returns

A page of list membership objects. Each membership includes the contact_external_id so you can correlate memberships with your own systems.

Example response

json

{
  "object": "array",
  "has_more": true,
  "next": "/v1/lists/3d4e06a3-544b-4cc7-924e-e077ef133cf6/memberships?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "list_membership",
      "id": "80d43a50-e9a8-41ea-8aa2-7d361292f0d9",
      "list_id": "3d4e06a3-544b-4cc7-924e-e077ef133cf6",
      "contact_id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      "contact_external_id": "ABC-123",
      "urls": {
        "contact": "/v1/contacts/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

Create list memberships

POST /v1/lists/:list_id/memberships

Adds contacts as members to a list.

INFO

You can only add contacts that are synced through the API to a list via the API.

Parameters

Name	Optional	Type	Description
list_id	required	string	The ID of the list to add members to.
ids	required	array	An array of contact IDs to add to the list. Can be a maximum of 1000 values.
external	optional	boolean	Whether the `ids` parameter is an array of `contact.id` or `contact.external_id`. Defaults to `false`.
external_list	optional	boolean	If the list lookup is done by `external_id` instead of `id`. Defaults to `false` (lookup by `id`).

You can supply the external and external_list parameters in the payload or as query parameters like:

POST /v1/lists/:list_id/memberships?external&external_list

The external parameter applies to the ids in the payload (the contacts), and external_list applies to the list_id in the URL. They can be supplied independently.

Example payloads

Contact ID

json

{
  "ids": ["937ccbe2-4cb5-4c76-96bf-29510b514dfa"]
}

External ID

json

{
  "ids": ["1234567890"],
  "external": true
}

Returns

A success message and a 201 status code if successful.

Example responses

Success response (201)

json

{
  "message": "List memberships created successfully"
}

Error response (404)

json

{
  "error": "Contacts not found for 2 ids",
  "ids_not_found": ["abc123", "def456"]
}

Error response (422)

json

{
  "error": {
    "ids": ["size must be within 1 - 1000"],
    "external": ["must be a boolean"]
  }
}

Errors

Code	Description
404	List with the given ID was not found.
404	Contacts with the given IDs were not found.
422	Invalid request, missing required parameters or supplied parameters are invalid

Delete list memberships

DELETE /v1/lists/:list_id/memberships

Removes contacts from a list.

Parameters

Name	Optional	Type	Description
list_id	required	string	The ID of the list to remove members from.
ids	required	array	An array of contact IDs to remove from the list. Can be a maximum of 1000 values.
external	optional	boolean	Whether the `ids` parameter is an array of `contact.id` or `contact.external_id`. Defaults to `false`.
external_list	optional	boolean	If the list lookup is done by `external_id` instead of `id`. Defaults to `false` (lookup by `id`).

The external parameter applies to the ids in the payload (the contacts), and external_list applies to the list_id in the URL. They can be supplied independently.

Returns

A success message and a 200 status code if successful.

Example responses

Success response (200)

json

{
  "message": "List memberships deleted successfully"
}

Error response (404)

json

{
  "error": "Contacts not found for 2 ids",
  "ids_not_found": ["abc123", "def456"]
}

Error response (404)

json

{
  "error": "No memberships found for the contacts with the given IDs."
}

Error response (422)

json

{
  "error": {
    "ids": ["size must be within 1 - 1000"],
    "external": ["must be a boolean"]
  }
}

Errors

Code	Description
404	List with the given ID was not found.
404	Contacts with the given IDs were not found.
404	No memberships found for the contacts with the given IDs.
422	Invalid request, missing required parameters or supplied parameters are invalid

Lists ​

Endpoints ​

List lists ​

Parameters ​

Returns ​

Retrieve a list ​

Parameters ​

Returns ​

Create a list ​

Parameters ​

Returns ​

Errors ​

Update a list ​

Parameters ​

Returns ​

Errors ​

Delete a list ​

Parameters ​

Returns ​

Errors ​

List Memberships ​

List list memberships ​

Parameters ​

Returns ​

Create list memberships ​

Parameters ​

Returns ​

Errors ​

Delete list memberships ​

Parameters ​

Returns ​

Errors ​

Lists

Endpoints

List lists

Parameters

Returns

Retrieve a list

Parameters

Returns

Create a list

Parameters

Returns

Errors

Update a list

Parameters

Returns

Errors

Delete a list

Parameters

Returns

Errors

List Memberships

List list memberships

Parameters

Returns

Create list memberships

Parameters

Returns

Errors

Delete list memberships

Parameters

Returns

Errors