List Management APIs

Use this endpoint to create a new list.

You can create a new list to group a subset of records for specific communications. For example:

• Only team members in Denver, not California, are notified by HR that the office will be closed following a blizzard (i.e., notifications based on geographic area lists)

• Customers who previously bought a harness for their dog will receive notifications when other dog accessories are on sale (i.e., lists based on previous purchase history)

Endpoint

POST/rest/v1/my/list

Note: You must send your request in JSON format.

Path Parameters

None

Query Parameters

None

Body

• listName: string, *Required

  • Give your list a unique and descriptive name. This will also appear on the CPaaS Portal List Management or Customer Portal List Management page.

• headerInfo: array, *Required

  • These are the columns of your list.

• description: string, optional

  • Include a unique and descriptive statement about your list.

• sharing: string, optional

  • Specify if your list is "public" or "private". If your list is public, anyone on your account can see and use it. If your list is private, only you can see and use it.

Sample Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "listName":"my new contact list",
    "sharing":"public",
    "headerInfo":[
        "elementId",
        "triggerType",
        "testFlowId",
        "smsMessage",
        "callingNumber",
        "calledNumber",
        "sessionID",
        "startDate",
        "startTime",
        "region",
        "outboundMessage",
        "dialAction",
        "menuTreeAction",
        "transferFinalDisposition",
        "regexResult",
        "transferAction"
        ],
    "description":"this will contain information about my new list"
}

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data":
      {
      "listName":"my new contact list",
      "description":"this will contain information about my new list",
      "sharing":"public",
      "modifiedDate":"2021-04-09T19:55:19.000Z",
      "modifiedBy":"steven@jayacompany.com",
      "createdDate":"2021-04-09T19:55:19.000Z",
      "createdBy":"steven@jayacompany.com",
      "customerId":"1140843",
      "listId":"6070b6c765c3be0008e2051e"},
      "error":null
      }
  }

Use this endpoint to add an element to an existing list. An element is a record, or row of your list.

You can add a new subscriber to notifications or promo campaigns with this endpoint.

Endpoint

POST/rest/v1/my/list/{listId}/element

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• elementInfo: object

  • You must include the same header values used in the list you’re adding the element to (e.g., if “phonenumber” is a header value in your list, and you just include “phone” in the body, you’re request won’t be successful).

Sample Request

1
2
3
4
5
6
7
8
9
{
  "elementInfo": {
    "metadata": {
      "name": "string",
      "age": 0,
      "...": "string"
    }
  }
}

Sample Response

1
2
3
4
5
6
{
  "data":{
       "ok":true
      }
  "error":null
}

Use this endpoint to upload new list elements via CSV file to an existing list.

You can add subscribers to a newly created list via a CSV file exported from a CRM tool or other repository. Using this endpoint the header values (columns) and row elements (records) from your CSV file populate the empty list.

Endpoint

PUT/rest/v1/my/list/{listId}/csv

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• CSV file: *Required

  • Your file must be comma separated with no spaces in the header values (e.g., “phonenumber” is acceptable but “phone number” is not acceptable), and no duplicate header values (e.g., if your headers were “firstname”, “lastname”, “lastname” your request won’t be successful).

Sample Request

1
2
3
{
  "csv": "string"
}

Sample Response

1
2
3
{
  "ok": "true"
}

Use this endpoint to upload new list elements via JSON to an existing list.

You can add subscribers to a newly created list via code. Using this endpoint the header values (headerInfo) and row elements (metadata) from your code populate the empty list.

Endpoint

PUT/rest/v1/my/list/{listId}

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• headerInfo: array

  • These are the columns of your list.

• elements: object[]

  • These are the rows of your list (i.e., record details).

Sample Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "metadata": [
        {
            "name": "john",
            "lastName": "doe",
            "phone": "+1293943943"
        },
        {
            "name": "jane",
            "lastName": "dee",
            "phone": "+323483483"
        }
    ]
}

Sample Response

1
2
3
4
5
6
{
  "data":{
       "ok":true
      }
  "error":null
}

Use this endpoint to add a new header field to an existing list.

Note: You cannot remove a new field once it's added. Ensure the field name and spelling are correct before executing your request.

Endpoint

PUT/rest/v1/my/list/{listId}/field

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• field: string, *Required

  • The new field name for your list.

    Note: The new field name cannot contain any spaces and must be unique for the list.

• value: string

  • Include a default value that will be applied to all existing list records.

Sample Request

1
2
3
4
{
"field": "active",
"value": true
}

Sample Response

1
2
3
4
5
6
{
"data": {
"ok": true
},
"error": null
}

Use this endpoint to retrieve the status of your list.

When you create a new list and add elements via CSV file or JSON, if your list is very large it may take some time for the elements to be processed. The status let's you know the state of your list and when the elements are successfully added. List statuses include: created, processing, completed, and failed.

Endpoint

GET/rest/v1/my/list/{listId}/status

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

None

Sample Request

GET /rest/v1/my/list/60391b9aade7cb1af64d7d48/status

Sample Response

1
2
3
4
{
  “status”: “completed”,
  “message”: “List was processed successfully”
}

Use this endpoint to update details of a single existing element.

You can update the details for one record on your list with this endpoint. For example, if a customer provides an update for their preferred method of contact or new phone number.

Endpoint

PUT/rest/v1/my/list/{listId}/element

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• updateInfo: object

  • You must include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list, and you just include “phone” in the body, you’re request won’t be successful). If a nonexistent header is sent you would also get an error (e.g., if you added in “country”).

• findConditions: object

  • You must include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list and you use “phone” as a condition, a match won’t be found ).

• elementId: string

  • The Element ID is the randomly generated set of characters assigned to your element. Your Element ID can be found in the success response when you Create a New Element.

  Note: elementId and findConditions are mutually exclusive. Use one or the other to find the element you want to lookup.

Sample Request

Using findConditions:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "updateInfo":
        {
            "name": "john",
            "lastName": "doe",
            "phone": "+1293943943"
        },
    "findConditions":
        {
            "phone": "+283892893"
        }
}

Or using elementId:

1
2
3
4
5
6
7
8
9
{
    "updateInfo":
        {
            "name": "john",
            "lastName": "doe",
            "phone": "+1293943943"
        },
    "elementId": “6070b6c765c3be0008e2051e”
}

Sample Response

1
2
3
4
5
6
{
  "data":{
       "ok":true
      }
  "error":null
}

Use this endpoint to update the details of more than one elements in the same existing list.

You can update the details for multiple records in your list with this endpoint. For example, if there is an annual update for all customer preferred methods of contact and many recipients have new phone numbers.

Endpoint

PUT/rest/v1/my/list/{listId}/elements

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• updateInfo: object

  • You must include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list, and you just include “phone” in the body, you’re request won’t be successful). If a nonexistent header is sent you would also get an error (e.g., if you added in “country”).

• findConditions: object

  • You must include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list and you use “phone” as a condition, a match won’t be found ).

Sample Request

1
2
3
4
5
6
7
8
9
10
11
{
    "updateInfo":
        {
            "name": "john",
            "phone": "+1293943943"
        },
    "findConditions":
        {
            "phone": "John"
        }
}

Sample Response

1
2
3
4
{
  "updatedElements": 2,
  " matches": 3
}

Note: updatedElements is the number of matched elements that were actually updated. matches is the number of elements that match the conditions in findConditions.

Use this endpoint to initiate exporting an existing list associated with your account.

You can download the entire list of records in CSV or JSON format.

Note: Use this endpoint followed by the Retrieve an Exported List endpoint, below. This endpoint just initiates the export. You must then use the Retrieve an Exported List endpoint to download the file.

Endpoint

POST/rest/v1/my/list/{listId}/export

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• type:

  • You can export your list as a CSV file ("csv") or JSON ("json").

Sample Request

CSV file:

1
2
3
{
  "type": "csv"
}

Or JSON:

1
2
3
{
  "type": "json"
}

Sample Response

1
2
3
4
5
6
7
8
status: 200

{
    "data": {
        "ok": true
    },
    "error": null
}

Use this endpoint to determine the status of an exported list and download it.

Note: Use this endpoint following the Export a List endpoint, above. You must use the Export a List endpoint first, to initiate the export, and then use this endpoint to download it via the URL in the response.

Available export statuses include: ready (i.e., the file is done), processing, and failed.

Endpoint

GET/rest/v1/my/list/{listId}/export/status

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

None

Sample Request

GET/rest/v1/my/list/6058ae623886e50008bd0833/export/status

Sample Response

1
2
3
4
5
6
7
8
9
10
11
Status: 200

{
    "data": {
        "status": "ready",
        "count": 4,
        "createdDate": "2021-07-01T17:09:17.418Z",
        "url": "https://csv-export-list-management-qa.s3.amazonaws.com/60dcbc36f57e5d0009d8025d-9999999-1625159357.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA23IMHRNJLY5VQ2VZ%2F20210701%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210701T171201Z&X-Amz-Expires=300&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEOn%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJGMEQCIBMTLATutNs4KyKHbMR%2Bp3%2FQJkdFR1OHIY6fuKZnEmZHAiBkXT10a1RmpSI1%2FgTgOpcNnoa%2F9z1FT0hxepibpxGp8yqrAgjC%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAAaDDc0NTczOTM1NzAxMCIMQuk5qxDMBZkSO9nNKv8BbGOOP3Wq%2BqF%2Bwuqc3Q2LE0Uaawi1rlHEhzil%2F%2Faa19Ozpr1ykfScN1pf1AsK%2FWDgkHGXFow4fqbfDbsEcUGH8vPfE739uWlWvcA4MCvYlqYpe3PEH1gI4%2BuegZjRhds8%2Bz1CGqWX3swrRZWodyopkLnRKlHUiekfDwBxxn4aQR%2F14Wq%2BLuN9%2B6B2r7zbyXDPK6G59DcIv%2F1AsmmIJQOEGViF5t7Cw9cZv5n%2B0mDPzoXg3x%2BXX8FtPAUK%2FTQ9Lo1BpvH90HgUBoNxsAEi1szx9txqUr3hHJZzjL%2BP%2B54tPs24dt61MArhu34mQZ5AfaQoLHFVsFotyDI4Td7fHJroMKXm94YGOpsBXfFn3WHLV0%2Bq4%2FYy4C5SmGC9IS%2FnWoLHw3i1Bu9mH0UElmkQ2w96XbkbKhQXUtVsyk06Y3ZDBdibGC5RTbCPsJKTmP%2FpGb5tmyEQbrSaSlz7ORaYi7NpAz5JQ%2B2Fv7Slw3PE60r9wGq4A911%2F0ZsIFJ%2Bf8sQiFANYwYSEZ4k%2BzTNyNi8rNVS0rrzCxWeaSlV5rQwYi7qQ0j1bHw%3D&X-Amz-Signature=aaa61ce30f4b27c74e51175547ecb5ab7c5c032c839f063e01120a1b11c79f91&X-Amz-SignedHeaders=host"
    },
    "error": null
}

Use this endpoint to delete a single element from an existing list.

You can remove one record from your list with this endpoint. For example, if a customer requests to unsubscribe from notifications.

Endpoint

DELETE/rest/v1/my/list/{listId}/element

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• findConditions: object

  • You must include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list and you use “phone” as a condition, a match won’t be found ).

• elementId: string

  • The Element ID is the randomly generated set of characters assigned to your element. Your Element ID can be found in the success response when you Create a New Element.

Note: elementId and findConditions are mutually exclusive. Use one or the other to find the element you want to lookup.

Sample Request

Using findConditions:

1
2
3
4
5
6
{
    "findConditions":
        {
            "phone": "+283892893"
        }
}

Or using elementId:

1
2
3
{
    "elementId": “6070b6c765c3be0008e2051e”
}

Sample Response

1
2
3
4
5
6
{
  "data":{
       "ok":true
      }
  "error":null
}

Use this endpoint to delete multiple elements from the same list.

You can remove multiple records from your list with this endpoint. For example, if there is an annual update and many recipients elect to unsubscribe from notifications.

Endpoint

DELETE/rest/v1/my/list/{listId}/elements

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• findConditions: object

  • Include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list and you use “phone” as a condition, a match won’t be found ).

    Note: If you include findConditions as an empty object (e.g., { "findConditions": {}}) an error will be returned. Check out the Archive All List Elements endpoint instead if you want to remove all list elements.

  • Or, include modifiedDate or createdDate to bulk delete records based on a specific date range.

    Note: startDate, endDate, and timezoneOffsetHours are required to set the date range. timezoneOffsetHours converts database times and finds list records within the correct timespan (e.g., if you are located in Denver, Colorado (GMT-6), the parameter timezoneOffsetHours: 6 would return elements for your timespan adjusted to the correct timezone).

Sample Request

1
2
3
4
5
{    "findConditions":
        {
            "phone": "John"
        }
}

Sample Response

1
2
3
4
{
  "removedElements": 2,
  " matches": 3
}

Note: removedElements is the number of matched elements that were actually removed. matches is the number of elements that match the conditions in findConditions.

Use this endpoint to archive all elements in an existing list.

Note: Archiving all elements serves as a soft delete. You won't be able to retrieve your elements, so please triple check before removing all elements in a list.

Endpoint

PUT/rest/v1/my/list/{listId}/archive

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

None

Sample Request

PUT/rest/v1/my/list/6058ae623886e50008bd0833/archive

Sample Response

1
2
3
4
5
6
7
{
"data": {
"ok": true,
"elementsUpdated": 25
},
"error": null
}

Use this endpoint to soft delete a list associated with your account.

Note: If you delete a list, it will be gone forever. Please triple check before deleting a list.

The deleted list will no longer appear on the List Management page. You cannot delete a list assigned to an active Engage campaign. Please deactivate the campaign, or remove the list you want to delete and assign a different list to the campaign, before deleting a list assigned to an active campaign. If you delete a list referenced in a List Action within SmartFlows, the flow will not function correctly (e.g., the flow will not be able to match the list details). Please ensure the flow configuration is updated to match another list before deleting a list associated with flow.

Endpoint

DELETE/rest/v1/my/list/{listId}

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

None

Sample Request

DELETE /rest/v1/my/list/606380be9b369d000858f26c

Sample Response

1
2
3
{
  "ok": "true"
}

Use this endpoint to look up a single list element.

You can search for one record on your list with this endpoint and view metadata about that item. For example, you could pull in recipient details from your list into another system to automatically fill in their contact details.

Endpoint

POST/rest/v1/my/list/{listId}/find/element

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

• findConditions: object

  • You must include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list and you use “phone” as a condition, a match won’t be found ).

  • Use findConditions and a header value from your list to find the first empty record that matches your conditions. For example, to find missing customer phone numbers you could use:

    Copy

    1
    2
    3
    4
    5
    {
        "findConditions": {
            "phonenumber": ""
        }
    }

  • To search for an exact match: Use findConditions, a header value from your list, and include $eq before the value you want to find. If you do not include $eq, your search results will include any partial matches.

• elementId: string

  • The Element ID is the randomly generated set of characters assigned to your element. Your Element ID can be found in the success response when you Create a New Element.

Note: elementId and findConditions are mutually exclusive. Use one or the other to find the element you want to lookup.

Sample Request

Using findConditions:

1
2
3
4
5
6
{
    "findConditions":
        {
            "phone": "+283892893"
        }
}

Or using elementId:

1
2
3
{
    "elementId": “6070b6c765c3be0008e2051e”
}

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "data": {
        "elements":
            {
                "id": "605a9082b355eb65b1d1c150",
                "listId": "605a8fbb26949b64edb55f1f",
                "deleteFlag": false,
                "modifiedBy": "steven@jayacompany.com",
                "createdBy": "steven@jayacompany.com",
                "modifiedDate": "2021-03-24T01: 06: 08.000Z",
                "createdDate": "2021-03-24T01: 06: 08.000Z",
                "metadata": {
                    "name": "Diego",
                    "age": "30",
                    "phone": "+15550000001",
                    "id": "1234567890"
                }
            },
        "matches": 1
    },
    "error": null
}

Use this endpoint to lookup multiple elements from a list.

You can search for multiple records on your list with this endpoint and view metadata about them. For example, you could pull in recipient details from your list into another system to automatically fill in contact details.

Endpoint

POST/rest/v1/my/list/{listId}/find/elements

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

• page: default 1

  • The number of pages your query will return. Max value is 100.

• pageSize: default 10

  • The number of records included on each page of results your query will return. If your query is too large (e.g., one thousand elements are identified), an empty list will be returned.

Note: Only the first 10 records on your list will be returned per the default values above.

Body

• findConditions: object

  • You must include the same header value(s) used within the list (e.g., if “phonenumber” is a header value in your list and you use “phone” as a condition, a match won’t be found).

  • Use findConditions and a header value from your list to find all of the empty records that match your conditions. For example, to find missing customer phone numbers you could use:

    Copy

    1
    2
    3
    4
    5
    {
        "findConditions": {
            "phonenumber": ""
        }
    }

• To search for an exact match: Use findConditions, a header value from your list, and include $eq before the value you want to find. If you do not include $eq, your search results will include any partial matches.

Sample Request

1
2
3
4
5
{    "findConditions":
        {
            "phone": "John"
        }
}

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "data": {
        "elements": [
            {
                "id": "605a9082b355eb65b1d1c150",
                "listId": "605a8fbb26949b64edb55f1f",
                "deleteFlag": false,
                "modifiedBy": "steven@jayacompany.com",
                "createdBy": "steven@jayacompany.com",
                "modifiedDate": "2021-03-24T01: 06: 08.000Z",
                "createdDate": "2021-03-24T01: 06: 08.000Z",
                "metadata": {
                    "name": "Diego",
                    "age": "30",
                    "phone": "+15550000001",
                    "id": "1234567890"
                }
            }
        ],
        "count": 1,
        "hasMore": false,
        "matches": 1
    },
    "error": null
}

Note: matches is the number of elements that match the conditions in findConditions.

Use this endpoint to get data associated with a specific list.

Easily manage your list and view associated metadata in one location. You can view data about a list (e.g., name, headers, elements, etc.) and compare it with another system.

Endpoint

GET/rest/v1/my/list/{listId}

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

• page: default 1, *Required

  • The number of pages your query will return. Max value is 100.

• pageSize: default 10, *Required

  • The number of records included on each page of results your query will return. If your query is too large (e.g., one thousand elements are identified), an empty list will be returned.

Note: Only the first 10 records on your list will be returned per the default values above.

• search: optional

  • Find list elements with a specific value (e.g, search=John would return any elements including the name John).

    Note: If you include the search parameter in your request, any startDate, endDate, and modified parameters will be omitted.

• startDate: optional

  • Find list elements created on a specific date (e.g., startDate=2021-6-17 would return any elements created on June 17, 2021).

• endDate: optional

  • Include both startDate and endDate to find list elements created within a specific timespan (e.g., startDate=2021-6-17&endDate=2021-6-18 would return any elements created from June 17, 2021 through June 18, 2021).

• modified: optional

  • Find list elements modified on a specific date or within a specific timespan (e.g., startDate=2021-6-17&endDate=2021-6-18&modified=true would return any elements modified from June 17, 2021 through June 18, 2021).

Note: If you include the startDate parameter in your request, the endDate and modified parameters are optional. But if startDate is not included and the endDate and modified parameters are included, they will be omitted and the request will retrieve all list elements.

• timezoneOffsetHours: integer, *Required if you include the startDate parameter in your request

  • Include your timezone to convert database times and find list elements within the correct timespan (e.g., if you are located in Denver, Colorado (GMT-6), the parameter timezoneOffsetHours: 6 would return elements for your timespan adjusted to the correct timezone).

Body

None

Sample Request

GET rest/v1/my/list/6070be393d4b3c00082484bd?page=1&pageSize=10

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
"data":{
    "listId":"6070be393d4b3c00082484bd",
    "sharing":"private",
    "listName":"myListt",
    "description":null,
    "headerInfo":[
        "name",
        "lastName",
        "phone"
        ],
    "createdBy":"steven@jayacompany.com",
    "data":[
        {
        "name":"john",
        "lastName":"doe",
        "phone":"+1293943943",
        "_elementId":"6070bf5d3d4b3c00082484be"
        },
        {
        "name":"jane",
        "lastName":"dee",
        "phone":"+323483483",
        "_elementId":"6070bf5d3d4b3c00082484bf"
        }
        ],
    "pageSize":"10",
    "hasMore":false
    },
    "error":null
}

Use this endpoint to get a total count of the lists associated with your account.

You can view how many lists have been created and compare it with another system.

Endpoint

GET/rest/v1/my/list/all/count

Path Parameters

None

Query Parameters

None

Body

None

Sample Request

GET/rest/v1/my/list/all/count

Sample Response

1
2
3
{
  "total": 20
}

Use this endpoint to get a total count of the elements in a specific list.

You can view how many records are included in a list and compare it with another system. Use your record count to monitor things like a growing opt-out list or any significant changes in recipient totals.

Endpoint

GET/rest/v1/my/list/{listId}/count

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

None

Sample Request

GET /rest/v1/my/list/6070be393d4b3c00082484bd/count

Sample Response

1
2
3
{
  "total": 20
}

Use this endpoint to get the metadata for a specific list associated with your account.

You can view metadata (e.g., time zone) and “version control” details (e.g., date it was created, who most recently modified it) about a list.

Endpoint

GET/rest/v1/my/list/{listId}/information

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

None

Sample Request

GET /rest/v1/my/list/6070be393d4b3c00082484bd/information

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "data": {
        "listName": "myListt",
        "description": null,
        "sharing": "private",
        "modifiedDate": "2021-04-09T20:55:57.709Z",
        "modifiedBy": "steven@jayacompany.com",
        "createdDate": "2021-04-09T20:49:34.000Z",
        "createdBy": "steven@jayacompany.com",
        "deleteFlag": false,
        "customerId": "1140843",
        "listId": "6070be393d4b3c00082484bd",
        "headerInfo": [
            "name",
            "lastName",
            "phone"
        ]
    },
    "error": null
}

Use this endpoint to update the metadata for a specific list associated with your account.

You can update list data such as the list name, description, and time zone.

Endpoint

PUT/rest/v1/my/list/{listId}/update

Note: You must send your request in JSON format.

Path Parameters

• listId: string, *Required

  • The List ID is a randomly generated set of characters assigned to your List. Your List ID can be found in the success response when you Create a New List, or using the Retrieve All Lists Data endpoint.

Query Parameters

None

Body

None

Sample Request

PUT /rest/v1/my/list/6058ae623886e50008bd0833/update

1
2
3
4
5
{
  "description":"new description", 
  “listName”: “new listname”, 
  “sharing”: “private”
}

Note: sharing can be either private or public.

Sample Response

{
  "data":{
       "ok":true
      }
  "error":null
}

Use this endpoint to get the metadata for all of the lists associated with your account.

You can view metadata about all of your lists (e.g., name, time zone, etc.) and “version control” details (e.g., date it was created, who most recently modified it).

Endpoint

GET/rest/v1/my/list/all

Path Parameters

None

Query Parameters

• page: default 1

  • The number of pages your query will return. Max value is 100.

• pageSize: default 10

  • The number of records included on each page of results your query will return. If your query is too large (e.g., one thousand elements are identified), an empty list will be returned.

Note: Only the first 10 records on your list will be returned per the default values above.

Body

None

Sample Request

GET /rest/v1/my/list/all?page=1&pageSize=10

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
    "data": {
        "lists": [
            {
                "customerId": "1140843",
                "listName": "we need a long list name to check what is happen",
                "description": "description ti",
                "sharing": "public",
                "deleteFlag": false,
                "modifiedDate": "2021-04-09T21:42:02.088Z",
                "modifiedBy": "steven@jayacompany.com",
                "createdDate": "2021-03-22T14:44:53.000Z",
                "createdBy": "steven@jayacompany.com",
                "listId": "6058ae623886e50008bd0833",
                "headerInfo": [
                    "a",
                    "asdf",
                    "asdfsdg",
                    "asdfgfdsghgfhd",
                    "asddfgghsghf"
                ]
            },
            {
                "customerId": "1140843",
                "listName": "Demo List",
                "description": null,
                "sharing": "private",
                "deleteFlag": false,
                "modifiedDate": "2021-03-30T14:52:42.635Z",
                "modifiedBy": "e0742432b78d1166",
                "createdDate": "2021-03-23T15:49:04.000Z",
                "createdBy": "e0742432b78d1166",
                "listId": "605a0f97f9faca0009563e2e",
                "headerInfo": [
                    "triggerType",
                    "testFlowId",
                    "transferAction"
                ]
            }
],
        "pageSize": 10,
        "hasMore": true
    },
    "error": null
}