Forms AJAX Submission Endpoint



What’s happening?

Now live, a new form submission endpoint is being released for the Forms API. The new endpoint now supports both CORS AJAX submissions and the new forms-related GDPR functionality. The existing form submission endpoint will continue to function as usual.

What’s changing?

With the release of the new form submission endpoint, integrators can take advantage of two powerful new features:

  • CORS AJAX Support: Previously, integrators that wanted to submit form data to the Forms API needed to implement custom scripts in a seperate server to proxy the form submission from their custom form to the HubSpot API. While HubSpot APIs that require authentication still don’t support CORS AJAX requests, the new form submission endpoint enables integrators to cut out the middle man (i.e. server-side scripts) and submit their custom forms directly to the Forms API.
  • GDPR Functionality: The new form submission endpoint also allows integrators to take advantage of HubSpot forms’ new [notice/consent]( features). The legalConsentOptions field is used to indicate that the visitor submitting the form provided their consent for communications and processing. The details included in this field are described in the endpoint’s documentation (see below).

When is this happening?

This feature is currently live; integrators can take advantage of the new form submission endpoint immediately. Check out the documentation for this endpoint here.The existing form submission endpoint will continue to function as usual.

Please don’t hesitate to post any questions or concerns in the comments below.


Hi @Derek_Gervais,

Thank you for the new legalConsentOptions section in the Forms API. It is a great and very timely improvement for us. A quick question: We'd like to include the default "marketing info" subscription in our post to the form, but it and its ID doesn't seem to be included in the get_subscriptions GET call. How can I find the ID for this default subscription? Is it possible to include in the legalConsentOptions section?

Thank you,



I can't seems to get it to work when using the Fetch api.
=> If I don't set the Content-Type header to application/json, the request is refused with a 415 error (wrong type of content)
=> If I DO set the Content-Type header, then the request is refused at the preflight stage with a "Request header field Content-Type is not allowed by Access-Control-Allow-Headers." which mean the server is not configured to allow this access control check for this header field.

Seems like there is an incoherence between the api headers expectations and the servers configurations to allow CORS requests.

That's my guess.

Let me know if you fix it or if I'm wrong in my analysis.


Hi folks,

@nflaherty that email type is the default type for in-app tools like sequences, and it's currently not accessible via the API. I'll touch base with the team for more information on how integrators using the forms API would/should work with that email subscription type.

@Fraggle this is a known issue, see the following topic:


What is the reasoning for requiring the posted data fields to match the fields in a built hubspot form?

In the existing endpoint (v2) you can create and empty form in hubpost and post data to it. If the posted field exists in hubpost contact properties, the data value is applied.

Can the v2 endpoint accept the gdpr related fields?



@Derek_Gervais I too have the same questions as @mattdev.

Additionally, with the v2 endpoint, you could include pageId in hs_context and, while not documented, it would actually count those form submissions against a specified HubSpot landing page. This worked great for us because we could capture form metrics on landing pages even though we were using non-native forms. I understand this probably was not inttentionally supported to begin with, but it was massively valuable to us and is now sorely missed with the v3 endpoint. Would it be possible to bring this functionality back to v3?

Without this and what @mattdev mentioned, we are debating whether we should move to v3 or stick with v2 and use custom contact properties to capture consent data, and then workflow rules to populate legal_basis.

Thanks for your consideration,


Hi @mattdev and @nflaherty

The new endpoint is designed to support server-side validation of the fields in the form, so that any submissions through the Forms API would be validated in the same way that submissions through HubSpot forms would be validated. The older endpoint processed submissions asynchronously, so it would be possible to send data or fields that wouldn't actually get updated for the contacts, and the new endpoint is designed to prevent that. That validation is enabled by default, but it can be bypassed using the skipValidation option in the request data.

@nflaherty the new endpoint does not support the pageId, but we'll check with the forms team to see if that can be added.


Hi @dadams, what did the forms team think of enabling pageId in the v3 endpoint? We will be going live with our implementation of v3 this week and are worried about the loss of analytics here. Knowing whether it is being considered or is in the pipe would ease our minds!

Thank you,


According to the docs for the v2 API "if no ipAddress is included, the IP address will be set to the IP of the system making the request to the Forms API". Not sure when this would be useful with v2, since AFAICT it would always be a server IP. With the v3 API supporting CORS requests, it seems like that behavior would be much more useful (especially since there isn't a particularly robust way to get a user's IP address from a JS app), but it doesn't seem to support auto-populating the IP address by default, resulting in the following warning message:

Is there any way to get the IP auto-populated from a JS/CORS request to the v3 API?


Welcome, @gabrielgrant!

You're correct that the v3 Forms API does not auto-populate any ipAddress value at this time.

Would any of these methods work for your purposes?

If you'd like to make a case for this feature to be added, please post on the HubSpot Community Ideas Forum with your use case. If you post, share the link below and I'll be happy to upvote it!


I'm not sure if this is the right place for this, but I just caught an issue with the v3 docs. It says the response object will return a 'thankYouMessage' field if specified, but I am receiving it back as 'inlineMessage'.


Welcome, @Adam_Volkman!

Thank you for bringing this to our attention! I see the same field returned and have updated the documentation accordingly.