Get contact list

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

Retrieving a single contact list is also how you discover its field schema — the set of columns (default and custom) that contacts in the list can have. There is no separate “fields schema” endpoint; the schema is returned in the sorted_fields array of this response.

Retrieving a contact list

Make a GET request to https://webapi.inboxroad.com/api/v2/contacts-lists/{blueprint_id}/ with a valid X-API-Key.

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

Path parameters

Param name	Description
blueprint_id	Unique identifier of the contacts list (UUID).

Response fields

Field name	Description
id	Unique identifier of the list (UUID).
label	Human-readable name of the list.
color	Hex color assigned to the list.
description	Description of the list.
unsub_success_redirect_url	Redirect URL after a successful unsubscribe, or null.
unsub_failed_redirect_url	Redirect URL after a failed unsubscribe, or null.
sorted_fields	Ordered list of field schema objects (see below).
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.

Field schema object (sorted_fields[])

Each contact list defines its own columns. Alongside the always-present default fields, a list can have an arbitrary number of custom fields. Use this array to discover the valid keys when creating or updating contacts.

Field name	Description
id	Unique identifier of the field (UUID).
label	Human-readable label of the field.
column_name	Snake-cased key used in contact payloads (derived from the label).
data_type	One of TEXT, INTEGER, FLOAT, BOOLEAN, DATE, DATETIME, CHOICE, MULTICHOICE, EMAIL, PATTERN.
required	Whether the field is required when creating a contact.
unique	Whether values must be unique within the list.
default	Default value, or null.
choices	Allowed values for CHOICE / MULTICHOICE fields, otherwise null.
max_length	Maximum length for text-like fields, or null.
read_only	Whether the field is set by the system and cannot be written.
pattern	Regex pattern for PATTERN fields, otherwise null.

Example response

{
  "id": "0fd3d5b4-1c0a-4e91-8a4f-0f17dc6dc5ab",
  "label": "Newsletter Subscribers",
  "color": "#7cb7de",
  "description": "Main newsletter contact list",
  "unsub_success_redirect_url": null,
  "unsub_failed_redirect_url": null,
  "sorted_fields": [
    {
      "id": "b1f3c0a2-1111-4e91-8a4f-0f17dc6dc5ab",
      "label": "Email",
      "column_name": "email",
      "data_type": "EMAIL",
      "required": true,
      "unique": true,
      "default": null,
      "choices": null,
      "max_length": 150,
      "read_only": false,
      "pattern": null
    },
    {
      "id": "c2a4d1b3-2222-4e91-8a4f-0f17dc6dc5ab",
      "label": "Plan",
      "column_name": "plan",
      "data_type": "CHOICE",
      "required": false,
      "unique": false,
      "default": "free",
      "choices": { "free": "Free", "pro": "Pro" },
      "max_length": null,
      "read_only": false,
      "pattern": null
    }
  ],
  "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
}

Possible response codes

Status code	Description
200	Contact list retrieved successfully.
401	Unauthorized.
404	Contact list not found.