List contact lists

If you have questions regarding this API, please visit our API FAQ page.

Listing contact lists

Make a GET request to https://webapi.inboxroad.com/api/v2/contacts-lists/ with a valid X-API-Key (see v2 authentication).

curl -X GET 'https://webapi.inboxroad.com/api/v2/contacts-lists/' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Response fields

Field name	Description
pagination	Pagination metadata for the results.
items	List of contact list objects.

Contact list object

Field name	Description
id	Unique identifier of the contact list (UUID).
label	Human-readable name of the list.
color	Hex color assigned to the list.
description	Description of the list (may be null).
created_at	Date and time the list was created.
fields_order	Ordered list of field ids defining column display order.
subscribers_count	Number of subscribed contacts.
unsubscribes_count	Number of unsubscribed contacts.
suppressed_count	Number of suppressed contacts.
integration_id	Linked integration id, or null.
contacts_import_task_id	Id of an in-progress import task, or null.
send_welcome_email	Whether a welcome email is sent to new contacts.
welcome_email_subject	Subject of the welcome email, or null.
welcome_email_template_id	Template id used for the welcome email, or null.
welcome_sender_profile_id	Sender profile id used for the welcome email, or null.

Example response

{
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total_count": 12,
    "total_pages": 1
  },
  "items": [
    {
      "id": "0fd3d5b4-1c0a-4e91-8a4f-0f17dc6dc5ab",
      "label": "Newsletter Subscribers",
      "color": "#7cb7de",
      "description": "Main newsletter contact list",
      "created_at": "2026-05-01T08:30:00Z",
      "fields_order": [
        "b1f3c0a2-1111-4e91-8a4f-0f17dc6dc5ab",
        "c2a4d1b3-2222-4e91-8a4f-0f17dc6dc5ab"
      ],
      "subscribers_count": 5421,
      "unsubscribes_count": 38,
      "suppressed_count": 12,
      "integration_id": null,
      "contacts_import_task_id": null,
      "send_welcome_email": false,
      "welcome_email_subject": null,
      "welcome_email_template_id": null,
      "welcome_sender_profile_id": null
    }
  ]
}

Query parameters

Param name	Possible values	Description
page	Integer	1-based page number. Default 1.
page_size	Integer	Results per page. Default 25.
search	String	Search lists by label.
ordering	asc, desc	Sort direction. Default desc.
order_by	label, subscribers_count, unsubscribes_count, suppressed_count, created_at, updated_at	Field to sort by. Default created_at.

For example:

curl -X GET 'https://webapi.inboxroad.com/api/v2/contacts-lists/?page=1&page_size=10&order_by=label&ordering=asc' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Pagination

Field name	Description
page	Current page number.
page_size	Number of results per page.
total_count	Total number of contact lists.
total_pages	Total number of available pages.