Create a new contact list

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

Create a new list in a given HubSpot portal to populate with contacts.

Creating this list show in the user interface, so beware that users will be able to edit and even delete lists that are programatically created in HubSpot.

Required Parameters How to use Description
OAuth Access Token or API Key Authorization: Bearer {token} header
or hapikey={key} query parameter.
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 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 do not get changed. 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.

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 repsonse will have a message field with more details about the specific problem with the data.

Filters

Filters are a list of descriptions that define 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 that operate based on the properties a contact has.

"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 below in the code sample).
  • NEQ — Meaning that the property is not equal to the value specified (as seen below in the code sample).
  • 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 value.
  • SET_NOT_ANY — (For enumerated properties only) Meaning that the property does not contain any of a semi-colon separated list of value.
  • 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 does not 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 are checking. Be sure to use the property name, not its label. Can be any property that exists in your portal.

OR "computed_property" attribute — the name of the computed property you are checking. Must be one of:

  • DATE_OF_LAST_FORM_SUBMISSION
  • NUMBER_OF_FORMS_FILLED_OUT

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

"type" attribute — the type of the property that you are checking.

List Membership — Filters that operate 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 portal. It can be static or dynamic.
  • NOT_IN_LIST — Meaning that the contact is not in the specified list.

"list" attribute — the list ID of the list you are referencing.

Form Submission — Filters that operate based on the forms that a contact has submitted.

"operator" attribute — must be one of:

  • HAS_FILLED_OUT_FORM — Meaning that the contact has filled out a certain form.
  • HAS_NOT_FILLED_OUT_FORM — Meaning that the contact has not 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 care about form submissions after the given time (given as a millisecond epoch time).

"beforeTimestamp" attribute — (optional) only care 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 the 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 that operate 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 has not 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 that operate based on the pages that a contact has viewed on your website.

"operator" attribute — must be one of:

  • HAS_PAGEVIEW_EQ — Meaning that the contact has visited a page with the given URL.
  • HAS_PAGEVIEW_CONTAINS — Meaning that the contact has visited a page with a URL containing the given text.
  • HAS_PAGEVIEW_MATCHES_REGEX — Meaning that the contact has visited a page with a URL matching the given regular expression.
  • NOT_HAS_PAGEVIEW_EQ — Meaning that the contact has not visited a page with the given URL.
  • NOT_HAS_PAGEVIEW_CONTAINS — Meaning that the contact has not visited a page with a URL containing the given text.
  • NOT_HAS_PAGEVIEW_MATCHES_REGEX — Meaning that the contact has not 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?hapikey=demo

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