There's a new version of the HubSpot API

Check out the new 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.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example URL: https://api.hubapi.com/contacts/v1/lists/226468/add?hapikey=demo The JSON sample below represents the contact IDs (VID) or emails that you need to pass in the body of your POST request to add the contact to your list: { "vids": [ 3057124, 5524274 ], "emails": [ "testingapis@hubspot.com" ] } If the request succeeds, you'll get an HTTP 200 response with a JSON object. In the "updated" field, you'll also get the contact IDs of any contacts that you've just added to the list. Here's the JSON response from the request made with JSON above: { "updated": [ 5524274, 5531874, 3057124 ], "discarded": [ ], "invalidVids": [ ], "invalidEmails": [ ] }