topic Re: Forms API for ad attribution in APIs & Integrations

Forms API for ad attribution

SeanCallahan — Mon, 01 Dec 2025 23:59:08 GMT

Hi,

I'm looking to get meta and google ad attribution working on a non-hubspot checkout form in BigCommerce. I was told by a hubspot customer service representitive that the Hubspot forms API should be used for this purpose to get ad attribution in the built in reporting tools.

She stated:

"Since the checkout page’s form isn’t a HubSpot Form and can’t be set up as a non-HubSpot form, the best option would be to use the Forms API. With this approach, make sure to include both the page URL and the HubSpot tracking cookie in your API submission to capture everything correctly".

I've reviewed the forms API docs here:

https://developers.hubspot.com/docs/api-reference/legacy/forms-v3-legacy/post-submissions-v3-integration-secure-submit-portalId-formGuid

It's unclear to me how to structure the payload to include UTM params and cookie data. Am I meant to create custom properties on a deal and match the property name in the forms API payload under the "fields" key, or is there some other method? I'm assuming the attribution would be done automatically by matching a clickID stored in the cookie and sent via the forms API with the Ad campign's clickID.

We're already pulling in the ads and seeing the data from the ad platforms, I just need a little clarification on how I'm intended to send the payload to do the attribution.

Thanks

Re: Forms API for ad attribution

BrandonWoodruff — Tue, 02 Dec 2025 14:45:32 GMT

Hi Sean,

From what I see, I think you are on the right track. Here are some approaches you can look at:
- Use the Forms API with the tracking cookie and full page URL so HubSpot can interpret UTMs and click data automatically.
- Optionally add custom contact properties for UTMs if you want more flexible reporting
- Skip creating deal level fields unless you have a specific reason since HubSpot Ads attribution is contact driven.

Let me know if this helps, or if you have any other questions!

✔️ Was I able to help answer your question? Help the community by marking it as a solution.

Brandon Woodruff
Senior Software Developer @ Pearagon

Still have questions? Reach out at brandon@pearagon.com

Re: Forms API for ad attribution

RubenBurdin — Mon, 15 Dec 2025 19:36:48 GMT

Hey @SeanCallahan , you’re thinking about it the right way. With the Forms API, you don’t “send UTMs” as a special object. You send a normal form submission (fields), plus a context that contains the HubSpot tracking cookie (hutk) and the page URL (pageUri).

HubSpot uses that to connect the submission back to the visitor session and pick up click IDs and attribution automatically. The payload shape and the context fields are documented here (https://developers.hubspot.com/docs/api-reference/legacy/forms-v3-legacy/post-submissions-v3-integration-secure-submit-portalId-formGuid )

For attribution specifically, HubSpot calls out that if you use the Forms API, you must pass the page URL and tracking cookie, and you still need the HubSpot tracking code present on the pages where the ad click lands so the cookie/session exist in the first place (https://knowledge.hubspot.com/ads/ads-attribution-in-hubspot )

So the key is: make sure context.pageUri is the full URL you want attributed (ideally including the querystring with utm_*, gclid, etc.), and context.hutk is the browser’s hubspotutk cookie value from that same user.

One quick question that changes the implementation: are you posting to the Forms API from the browser (client-side) or from your server? If it’s server-side, you’ll need to explicitly capture and forward the user’s hubspotutk and the original landing URL, because the server won’t have them by default.

Re: Forms API for ad attribution

SeanCallahan — Fri, 19 Dec 2025 20:44:37 GMT

Thanks, that all makes sense.

It wasn't quite clear to me that hubspot does the attribution in the background based on the cookie and page data via a form submission. I set up a front end form submission via the unauthenticated API on my order confirmation page and I do see some attribution now.

Since I've confirmed this is working the next step will be to submit to the authenticated API via our integrations server.

To get this set up for testing:

I created a sandboxed hubspot form with just the email property from a contact.
Note the portal and form ID for use in the form submission logic.
Impliment logic to submit the form on the order confirmation page of the webstore and include at a minimum:
- Customer email
- Hubspot cookie value from the hubspotutk cookie
- Page URL
During testing use private windows and ensure you have a new hubspot cookie set, and use a fresh email address for a contact.
You can simulate an ad click by taking the utm params from your ad and appending them to a url you visit in your browser before submitting an order.
Check hubspot form submissions for your attribution form and make sure it was successful.
Check the contact record properties for conversion information such as Google and Facebook click ID, IP address data, Recent conversion, etc.
Look at your ads and ensure there's a contact and revenue attribution

A few issues I've noticed,

Often click IDs are not set or set inconsistently however attributrion seems to mostly work regardless.
Sometimes there is timeline activity for ad clicks and a deal associated to a contact but the attribution does not work.
I've seen a few duplicate form submissions, perhaps if the page is refreshed. It would be advisable to prevent duplicate submissions.
Alternate email addresses on a contact can cause mis-attribution (split between contacts) and using the same hubspot cookie but testing with multiple emails will tend to attribute to the first contact to have that cookie ID set.

I'm wondering if it's significanlty more reliable to submit the attribution form server to server? Given that I see timeline activity and a deal but sometimes not attribution, this would indicate that the hubspot tracking script and cookies are not an issue but the form submission could be unreliable.

Re: Forms API for ad attribution

SamTassey — Fri, 19 Dec 2025 22:06:39 GMT

Hi @SeanCallahan,

Thanks so much for updating us on what worked for you!

Also big thanks to @RubenBurdin and @BrandonWoodruff for your help here so far! Would either of you happen to have any suggestions regarding @SeanCallahan's most recent question around what might be the most reliable approach here?

Thank you!

Sam, Community Manager