Add existing contacts to a list

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

Method Details

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} headeror 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.

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.

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": [
]
}