Manage contact lists

The following endpoints allow for creating contact lists and managing their life cycle.

List lists

Retrieve a list of contact lists

GET/workspaces/{workspaceId}/lists

Path parameters

workspaceId*string (uuid)

Response

200404

List of lists

Body

application/json

resultsarray of object

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200404

{
  "results": [
    {
      "id": "text",
      "name": "Sample Group",
      "description": "text",
      "createdAt": "2024-09-07T23:19:42.273Z",
      "updatedAt": "2024-09-07T23:19:42.273Z",
      "consentType": "single",
      "tags": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ]
}

Create list

Create a new contact list

POST/workspaces/{workspaceId}/lists

Path parameters

workspaceId*string (uuid)

Body

application/json

name*string

Name

Example: "Sample Group"

descriptionnullable string

consentTypenullable enum

singledouble

tagsnullable array of string (uuid)

Response

201404422

List created

Body

application/json

id*string

UUID

name*string

Name

Example: "Sample Group"

description*string

createdAtstring (date-time)

updatedAtstring (date-time)

contactCountinteger

Number of contacts in this group

consentTypeenum

Single or double opt-in

singledouble

tagsarray of string (uuid)

Tags associated with this group

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "Sample Group"
    }),
});
const data = await response.json();

Response

201404422

{
  "id": "text",
  "name": "Sample Group",
  "description": "text",
  "createdAt": "2024-09-07T23:19:42.273Z",
  "updatedAt": "2024-09-07T23:19:42.273Z",
  "consentType": "single",
  "tags": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Get list

Retrieve information about a contact list

GET/workspaces/{workspaceId}/lists/{listId}

Path parameters

workspaceId*string (uuid)

listId*string (uuid)

Response

200404

List

Body

application/json

id*string

UUID

name*string

Name

Example: "Sample Group"

description*string

createdAtstring (date-time)

updatedAtstring (date-time)

contactCountinteger

Number of contacts in this group

consentTypeenum

Single or double opt-in

singledouble

tagsarray of string (uuid)

Tags associated with this group

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists/{listId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200404

{
  "id": "text",
  "name": "Sample Group",
  "description": "text",
  "createdAt": "2024-09-07T23:19:42.273Z",
  "updatedAt": "2024-09-07T23:19:42.273Z",
  "consentType": "single",
  "tags": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Update list

Modify the details of a contact list such as name and description

PATCH/workspaces/{workspaceId}/lists/{listId}

Path parameters

workspaceId*string (uuid)

listId*string (uuid)

Body

application/json

namestring

Name

Example: "Sample Group"

descriptionnullable string

consentTypenullable enum

singledouble

tagsnullable array of string (uuid)

Response

200404422

List updated

Body

application/json

id*string

UUID

name*string

Name

Example: "Sample Group"

description*string

createdAtstring (date-time)

updatedAtstring (date-time)

contactCountinteger

Number of contacts in this group

consentTypeenum

Single or double opt-in

singledouble

tagsarray of string (uuid)

Tags associated with this group

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists/{listId}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200404422

{
  "id": "text",
  "name": "Sample Group",
  "description": "text",
  "createdAt": "2024-09-07T23:19:42.273Z",
  "updatedAt": "2024-09-07T23:19:42.273Z",
  "consentType": "single",
  "tags": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Delete List

Remove a contact list, all contacts will be removed from the list

DELETE/workspaces/{workspaceId}/lists/{listId}

Path parameters

workspaceId*string (uuid)

listId*string (uuid)

Response

204404

Deleted

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists/{listId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

404

{
  "code": "text",
  "message": "text"
}

List contacts in a list

Retrieve a list of all contacts in a list

GET/workspaces/{workspaceId}/lists/{listId}/contacts

Path parameters

workspaceId*string (uuid)

listId*string (uuid)

Query parameters

Response

200404

Contacts

Body

application/json

results*array of object

nextPageTokenstring

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists/{listId}/contacts', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200404

{
  "results": [
    {
      "id": "text",
      "computedDisplayName": "text",
      "createdAt": "2024-09-07T23:19:42.273Z",
      "updatedAt": "2024-09-07T23:19:42.273Z",
      "workspaceId": "text",
      "featuredIdentifiers": [
        {
          "key": "text",
          "value": "text"
        }
      ],
      "attributes": {
        "firstName": "John",
        "lastName": "Smith",
        "rating": 9.6,
        "cookiesAccepted": false,
        "labels": [
          "A",
          "B",
          "C"
        ]
      }
    }
  ],
  "nextPageToken": "text"
}

Add contacts to list

Add one or more contacts to a list

POST/workspaces/{workspaceId}/lists/{listId}/contacts

Path parameters

workspaceId*string (uuid)

listId*string (uuid)

Body

application/json

contactsarray of string (uuid)

contacts ids

Response

201404422

Contacts added

Body

application/json

itemsProcessed*integer

Example: 100

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists/{listId}/contacts', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

201404422

{
  "itemsProcessed": 100
}

Remove contacts from list

Remove one or more contacts from a list

DELETE/workspaces/{workspaceId}/lists/{listId}/contacts

Path parameters

workspaceId*string (uuid)

listId*string (uuid)

Body

application/json

contactsarray of string (uuid)

contacts ids

Response

200404422

Contacts removed

Body

application/json

itemsProcessed*integer

Example: 100

Request

JavaScriptCurlPython

const response = await fetch('/workspaces/{workspaceId}/lists/{listId}/contacts', {
    method: 'DELETE',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200404422

{
  "itemsProcessed": 100
}