There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. Your API Keys could be deactivated at any time after Nov. 30th, and we recommend that you migrate to Private Apps as soon as possible so you do not lose business-critical functionality.

Add existing contacts to a list

Last updated June 17, 2020

POST /contacts/v1/lists/:list_id/add

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

Add contact records that have already been created in the system to a contact list. You can add multiple records at once, either by vid or by email address. Up to 500 records can be added to a list in a single request, including records specified by ID and by email.

Please note that you cannot manually add contacts to dynamic lists. To determine whether a list is dynamic or static, when you get a list, you will see a flag called dynamic that equates to true or false.

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 ID Used in the request URL You need to include the ID for the list you're adding the lead to. You can search for lists using the get lists method.
vids Used in the request body The contact IDs of the contacts that you're adding to the list. Up to 500 total contacts can be added in a single request.
emails Used in the request body The email addresses of the contacts that you're adding to the list. Up to 500 total contacts can be added in a single request.
Optional Parameters How to use Description
None None No optional parameters for this method.

Example URL to POST to: https://api.hubapi.com/contacts/v1/lists/2/add?hapikey=demo

Returns a 404 error if there is no list with the specified ID.

Returns a 400 error if there is a problem adding the records to the list. There will be a message in the response JSON with more details about the error. You will get a 400 error if you try to add records to a dynamic list.