There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Create a new contact list

Last updated May 15, 2023

POST /contacts/v1/lists

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Required Scope:

crm.lists.write

This endpoint is used to create a new contact list in a given HubSpot account.

Creating this list will show in the UI, so be aware that users will be able to edit and even delete lists that are programmatically created in HubSpot.

Required parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.
List name "name":{list name}
Used in the request body JSON (see below)
You need to include a unique name for the list you're creating.
Optional parameters How to use Description
Dynamic list? "dynamic":{true or false}
Used in the request body JSON (see below)
Boolean value that you need to include that identifies whether your list is static or dynamic. Dynamic lists change as new contacts are created or updated. Static lists don't change. Defaults to false(static).
Filters "filters": [{filter data}]
Used in the request body JSON (see examples below)
A list of filters that you will use to define what contacts are included in your list. See below for more information about them. Defaults to an empty list, meaning no filters/criteria for the list.

Response details

  • Returns a 200 response with the JSON data of the new list on success.
  • Returns a 400 error with a JSON-formatted body if there is a problem with the list data you're sending. The response will have a message field with more details about the specific problem with the data.

Filters

Filters are a list of descriptions defining what should be in a list. This can be an empty list if you are creating a static list. Each filter is an object in a doubly nested array. Filters in the same list in the inner layer represent "AND" logic — all of these filters must be true for the group as a whole to be considered true. One of more of these groupings must be true for a given contact in order for that contact to be included in your list. This logical structure mirrors that in the list creation interface in the HubSpot product.

Depending on what kind of filter you're using, your filter object should have different attributes.

Contact properties — Filters based on contact details

"operator" attribute — must be one of:

  • IS_NOT_EMPTY — Meaning that property property is simply populated with any value.
  • IS_EMPTY — Meaning that the field is simply not populated at all.
  • EQ — Meaning that the property is equal to the value specified (as seen in the JSON sample provided).
  • NEQ — Meaning that the property is not equal to the value specified (as seen in the JSON sample provided).
  • CONTAINS — (For string properties only) Meaning that the property contains the value that you specify.
  • LT — (For number properties only) Meaning that the property contains a value less than the one you specify.
  • LTE — (For number properties only) Meaning that the property contains a value less than or equal to the one you specify.
  • GT — (For number properties only) Meaning that the property contains a value greater than the one you specify.
  • GTE — (For number properties only) Meaning that the property contains a value greater than or equal to the one you specify.
  • SET_ANY — (For enumerated properties only) Meaning that the property contains any of a semi-colon separated list of values.
  • SET_NOT_ANY — (For enumerated properties only) Meaning that the property doesn't contain any of a semi-colon separated list of values.
  • SET_EQ — (For enumerated properties only) Meaning that the property has exactly the values in a semi-colon separated list.
  • SET_NEQ — (For enumerated properties only) Meaning that the property doesn't have exactly the values in a semi-colon separated list.
  • SET_ALL — (For enumerated properties only) Meaning that the property has all of the values in a semi-colon separated list.

"property" attribute — the name of the property you're checking. Be sure to use the property name, not its label. Can be any property that exists in your account.

OR "computedProperty" attribute — the name of the computed property you're checking. Must be one of:

  • DATE_OF_LAST_FORM_SUBMISSION
  • NUMBER_OF_FORMS_FILLED_OUT

"value" attribute — the value that you're comparing the contact's property against. Not required for IS_NOT_EMPTY and IS_EMPTY operators.

"type" attribute — the type of the property you're checking.

List membership — Filters based on a contact's membership in other lists

"operator" attribute — must be one of:

  • IN_LIST — Meaning that the contact is in the specified list. This should be an existing list in your account. It can be static or dynamic.
  • NOT_IN_LIST — Meaning that the contact isn't in the specified list.

"list" attribute — the ID of the list you're referencing.

Form submission — Filters based on the forms that a contact has submitted

"operator" attribute — must be one of:

  • HAS_FILLED_OUT_FORM — Meaning that the contact filled out a certain form.
  • HAS_NOT_FILLED_OUT_FORM — Meaning that the contact hasn't filled out a certain form.

"form" attribute — the form ID of a given form.

"page" attribute — the page ID of a given landing page.

"afterTimestamp" attribute — (optional) only cares about form submissions after the given time (given as a millisecond epoch time).

"beforeTimestamp" attribute — (optional) only cares about form submissions before the given time.

All of these attributes are optional. If both "form" and "page" attributes are given, the filter will only match contacts that filled out the given form on the given landing page. If only "form" is given, the filter will match contacts that filled out the given form anywhere. If only "page" is given, the filter will match contacts that filled out any form on the given landing page. If neither is given, the filter will match contacts that have submitted at least one form.

Events — Filters based on events

"operator" attribute — must be one of:

  • HAS_EVENT — Meaning that the contact has had a given event happen to them.
  • NOT_HAS_EVENT — Meaning that the contact hasn't had a given event happen to them.

"value" attribute — the event ID.

"firstOccurrenceAfterTimestamp" attribute — (optional) only care about events for which the first occurrance for this contact occurred after the given time (given as a millisecond epoch time).

"firstOccurrenceBeforeTimestamp" attribute — (optional) only care about events for which the first occurrance for this contact occurred before the given time.

"lastOccurrenceAfterTimestamp" attribute — (optional) only care about events for which the last occurrance for this contact occurred after the given time.

"lastOccurrenceBeforeTimestamp" attribute — (optional) only care about events for which the last occurrance for this contact occurred before the given time.

"minOccurrences" attribute — (optional) only care about events that have occurred this many times or more.

"maxOccurrences" attribute — (optional) only care about events that have occurred this many times or less.

Pageviews — Filters based on the pages a contact viewed on your website

"operator" attribute — must be one of:

  • HAS_PAGEVIEW_EQ — Meaning that the contact visited a page with the given URL.
  • HAS_PAGEVIEW_CONTAINS — Meaning that the contact visited a page with a URL containing the given text.
  • HAS_PAGEVIEW_MATCHES_REGEX — Meaning that the contact visited a page with a URL matching the given regular expression.
  • NOT_HAS_PAGEVIEW_EQ — Meaning that the contact hasn't visited a page with the given URL.
  • NOT_HAS_PAGEVIEW_CONTAINS — Meaning that the contact hasn't visited a page with a URL containing the given text.
  • NOT_HAS_PAGEVIEW_MATCHES_REGEX — Meaning that the contact hasn't visited a page with a URL matching the given regular expression.

"value" attribute — the text to match against.

"firstOccurrenceAfterTimestamp" attribute — (optional) only care about views for which the first occurrance for this contact occurred after the given time (given as a millisecond epoch time).

"firstOccurrenceBeforeTimestamp" attribute — (optional) only care about views for which the first occurrance for this contact occurred before the given time.

"lastOccurrenceAfterTimestamp" attribute — (optional) only care about views for which the last occurrance for this contact occurred after the given time.

"lastOccurrenceBeforeTimestamp" attribute — (optional) only care about views for which the last occurrance for this contact occurred before the given time.

"minOccurrences" attribute — (optional) only care about views that have occurred this many times or more.

"maxOccurrences" attribute — (optional) only care about views that have occurred this many times or less.

Example URL to POST to:  https://api.hubapi.com/contacts/v1/lists

Please Note Your content type that you pass in the header of your request should be 'application/json'.