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.

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,
      "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.

Returns

A list object, which contains the list's id, external_id, title, email_address, list_type, list_source, memberships_count, 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,
  "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`.

Example payload

json

{
  "external_id": "XYZ-098",
  "title": "All Employees",
  "email_address": "all-employees@example.com",
  "list_type": "standard"
}

Returns

A success message and a 201 status code if successful.

Example responses

Success response (201)

json

{
  "message": "List created successfully"
}

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"]
  }
}

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_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`.

If you do not supply a parameter, its value will remain unchanged.

Example payload

json

{
  "title": "Sales Department",
  "email_address": "sales-department@example.com",
  "list_type": "department"
}

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.

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	Default	Description	Options
Pagination parameters			See pagination for more information.

Returns

A page of list membership objects.

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",
      "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`.

You can supply the external parameter in the payload or as a query parameter like:

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

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 add members to.
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`.

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