Update a contact list

Last updated April 12, 2019

POST /contacts/v1/lists/:list_id

Method Details

HTTP Methods:


Content Type:


Response Format:


Requires Authentication?


Rate Limited?






Update a list in a given HubSpot account.

Note that like creating a list, users will be able to edit and even delete these lists inside of the HubSpot user interface.

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 Unique identifier for the list that you're looking for.
Optional Parameters How to use Description
List Name Used in the request body JSON Include the name to update the name of the list.
Filters Used in the request body JSON (see below)

Any filters that you want to add to your list. You can find more details about the available filters and how they work here. Note: If you include any filter data in the request, it will replace any existing filters, not append.

Other List data Used in the request body JSON See creating a list for other data that can be set.

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

If the request succeeds, you'll get an HTTP 200 response with the updated data for the list, which represents that you have successfully refreshed the list in the system.

The response from this API call are standard REST-style HTTP response codes that mark success or failure, with meta information about the call that was made. If you've successfully updated the list, you will receive the updated list as a json object in the response body.

  • 200 when a list is updated and the data of the object that that was updated.
  • 400 when there is a problem with the form data. You'll receive a JSON formatted response with a message that provides more details.
  • 500 when an internal server error occurs. Please alert us in the API Forum if you receive an HTTP 500 error.