Lists

Learn how to retrieve the lists from Retainful API

Retrieves audience lists that you have set up in Retainful -> Audience -> Lists

Endpoint

GET /v2/lists

Query Parameters

Parameter	Type	Required?	Description
page	number	No	The page of results to retrieve. Defaults to 1 if not specified.
limit	number	No	Number of items to retrieve per page. Defaults to a system setting if not specified (e.g., 25).

Example:

GET /v2/lists?page=2&limit=20

This returns the second page of results with 20 items per page.

---

Example Request

GET /v2/lists?page=1&limit=10
Host: apiv2.retainful.net
Retainful-Api-Key: YOUR_API_KEY
Retainful-App-Id: YOUR_APP_ID

No request body is required for this endpoint. The parameters are passed as query strings.

---

Example Response (200 OK)

{
  "success": true,
  "data": {
    "lists": [
      {
        "uuid": "5Wce8EGvub9D7NCizYiE8qVGtNwbGMkzZVUL",
        "name": "Newsletter Subscribers",
        "created_at": 1740574233,
        "description": "This is a list of all newsletter subscribers"
      }
    ],
    "current_page": 1,
    "total_pages": 1,
    "total_items": 6,
    "items_per_page": 10
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful (true/false).
data.lists	array of objects	Collection of list objects.
lists[].uuid	string	Unique identifier of the list.
lists[].name	string	The display name of the list.
lists[].created_at	number (epoch)	Unix timestamp (seconds since the epoch) for when the list was created.
lists[].description	string	Optional text describing the list’s purpose, content, or any other relevant info.
data.current_page	number	The current page number in the paginated results.
data.total_pages	number	The total number of pages available given the current limit.
data.total_items	number	The total number of available lists.
data.items_per_page	number	Number of items per page.

---

Error Responses

• 401 Unauthorized Returned if the provided API key or App ID is missing or invalid.

  {
    "status": "error",
    "message": "Unauthorized access. Invalid or missing credentials."
  }

• 400 Bad Request Returned if the page or limit parameters are invalid (e.g., negative numbers).

  {
    "status": "error",
    "message": "Invalid 'page' or 'limit' parameter."
  }

• 500 Internal Server Error Returned if an unexpected error occurred on the server.

  {
    "status": "error",
    "message": "An unexpected error occurred."
  }

---

Best Practices & Notes

1. Pagination Defaults If you do not specify page or limit, Retainful will use default values (e.g., page = 1, limit = 25).

2. Efficient Data Handling For large datasets, paginate through results instead of trying to load everything in a single request.

3. Keep Credentials Secure Always safeguard your Retainful-Api-Key and Retainful-App-Id. Never expose these in public or client-side code.

4. Integrate Properly Use this list data to segment your contacts or display audiences in your application’s UI. Consistent referencing of list IDs is crucial for other Retainful endpoints.