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.

Add existing contacts to a list

Last updated May 15, 2023

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 private app access token Authorization: Bearer {token} header 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

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.