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.

Update an existing form

Last updated November 20, 2023

PUT /forms/v2/forms/:form_guid

Method Details

HTTP Methods:

PUT

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Update an existing form in a specified HubSpot portal. 

For any form, there may be a set of fields associated with that form in question. You can specify all the fields to be included in the form that you want to update with this API call.

If you're updating a form's name, you must use a unique name. Using the same name as a form name that already exists will return a 409 error. 

Example URL:  https://api.hubapi.com/forms/v2/forms/123d4ce5-bb6c-78b9-0e12-34cdeaa5a6f0

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.
Form GUID Used in the request URL The unique ID fo the form that you're updating. When updating a form, you need to explicitly specify which form you're updating, which is what this field is for.
Form Data to Update Used in the request body The data for the form that you're creating. This can include any number of data points, including fields. For an example of this data, please see the JSON code sample for POSTing and creating a new form below.
Optional Parameters How to use Description
Form Fields Used in the request body When updating a form, you have the ability to also edit any of the form fields that you'd like to be a part of the form you're updating.

However, if you specify fields in this call, it will override the fields that have already been set on this form. For example, in the request that you see below, "Last name" will now be the only field in the form, rather than being appended to the rest of the fields that already exist there.

Before adding a field to a form, you'll need to make sure that there's a corresponding contact property. You can create a new property to house any fields with the create property method.

The responses from this API call are standard REST-style HTTP response codes that mark success or failure, along with the JSON representing the form that you just updated:

  • 200 when a form is updated.
  • 401 when an unauthorized request is made.
  • 500 when an internal server error occurs.