Contact Lists API Overview

Contact lists are used to segment contacts into groups.  There are two main types of lists: dynamic (usually referred to as "active") and static.

Dynamic lists

Dynamic lists automatically add or remove contacts based on the list criteria. List membership is managed automatically and is updated whenever data changes for a contact. This means contacts can't be manually added or removed from a dynamic list.

Static lists

Static lists can also automatically include contacts, but only when the list is first created. After that, list membership won't change unless contacts are manually added or removed.

Syncing records

When syncing contact records through an integration, lists can be used to filter which records you're syncing. A dynamic list could be created to only include contacts with properties that matter to your integration (and you can use the API to poll for contacts in that list) instead of pulling all contacts and then filtering for that criteria separately.

More details about lists can be found in the here

Each list record will contain the following data. See creating a list for more details about the different filters that can be used.

  "parentId": 0,
      // Integer, read-only; The ID of the folder that the list belongs to.  Currently folders can only be managed in the HubSpot app.
  "dynamic": true,
      // Boolean; true if the list is a dynamic (active) list, false if static.
  "metaData": {
    "processing": "DONE",
        // String, read-only, one of DONE, REFRESHING, INITIALIZING, or PROCESSING;
        // DONE indicates the list has finished processing, any other value indicates that list membership is being evaluated.
    "size": 201,
        // Integer, read-only; The approximate number of contacts in the list.
    "error": "",
        // String, read-only; Any errors that happened the last time the list was processed.
    "lastProcessingStateChangeAt": 1477518645996,
        // Integer, read-only; A Unix timestamp (in milliseconds) of the last time that the processing state changed.
    "lastSizeChangeAt": 1479413042495
        // Integer, read-only; A Unix timestamp (in milliseconds) of the last time that the size of the list changed.
        // A value of 0 indicates that the list hasn't changed size since its creation.
  "name": "test emails",
      // String; The name of the list.
  "filters": [
      // This is a list of filters used to determine list membership. See creating a list for more details.
      // This field may be an empty list, for lists with no criteria.
        "withinTimeMode": "PAST",
        "checkPastVersions": false,
        "filterFamily": "PropertyValue",
        "type": "string",
        "property": "email",
        "value": "test",
        "operator": "STR_STARTS_WITH"
  "portalId": 62515,
      // Integer, read-only; The Hud ID that the list belongs to.
  "createdAt": 1335448813688,
      // Integer, read-only; A Unix timestamp (in milliseconds) of the time the list was created.
  "listId": 1,
      // Integer, read-only; The unique ID of the list.  This ID will not change, and should always be used to reference the list.
  "updatedAt": 1477944356444,
      // Integer, read-only; A Unix timestamp (in milliseconds) of the time that the list was last modified.
  "listType": "DYNAMIC",
      // String, read-only, one of DYNAMIC or STATIC;
      // DEPRECATED, use the 'dynamic' field to determine if the list is dynamic or static.
  "internalListId": 220441,
      // Integer, read-only; DEPRECATED, this is an internal field and should not be used. Use the 'listId' to reference the list.
  "deleteable": true
      // Boolean, read-only; If this is false, this is a system list and cannot be deleted.
      // This value may not be present for all lists. In those cases, this value may be treated as true (the list may be deleted).
      // When this value is true, you may still get an error deleting the list if it's in use by other lists or workflows.
      // See the documentation for deleting a list for more details.

Docs for this API