Create a new Contact flow


Hi guys,

I’m very very very new to HubSpot’s API, and have a quick question on the process for creating a new contact. I believe that each Contact is tied to a vid when they have converted via a Landing Page form or CTA. However, I have already developed the site prior to getting on-board with HubSpot, and as such, would need to use the API to create a new contact through my frontend.

I have seen the documentation ( but am wondering if I need to create any cookies manually from the response JSON to set the vid for this particular user when they have converted through my site’s form.

Many thanks in advance!


Hi @jerome.kwek

The contact vid is set by HubSpot when the contact is created, so you wouldn’t need to set it manually. Also, the tracking cookie HubSpot uses (named hubspotutk) is created by the HubSpot tracking code, so you’d need to have our tracking code installed on your site to have contacts tracked in HubSpot.

If you have visitors filling out forms, then you should use the Forms API to send that form data to HubSpot.

The Forms API also supports passing our tracking cookie (see the details for hs_context and hutk on that linked documentation page), so that you can see traffic data for the contacts in HubSpot.


Hi @dadams!

Thank you so much for your reply. One last confirmation, please see if his flow is correct, assuming that HubSpot’s tracking code has successfully been installed on the site:

  1. User visits site
  2. User enters email address (via site’s external form)
  3. HubSpot’s Submit data to a form API ( will be called with relevant details
  4. HubSpot adds User into Contacts, sets cookies for User on client side and returns a 302 response

Let me know if I got this right and I can get to integrating HubSpot with our site - Thanks once again @dadams! Much appreciated! :slight_smile:


Hi @jerome.kwek

Most of that is correct, except for #4 regarding the cookie.

The cookie is set by the HubSpot tracking code as soon as a visitor hits a page with the tracking code installed on it, and the tracking code uses that cookie to identify a specific visitor when collecting analytics data. The form submission just associates that tracking cookie to the contact record, so that we can display the analytics data collected for that visitor in the contact record.

Also, you’ll only get a 302 response from a form submission if you’re using a redirectUrl. If you’re making the requests to HubSpot server-side (we don’t support CORS or AJAX requests to our APIs), you generally wouldn’t use the redirect, so the submission would return a 204 No Content response.


Hi @dadams!

Thanks for your wonderful explanation! I guess with it accompanied by the API docs, I have successfully managed to add a Contact into my portal via the Forms API.

However, riding on this thread, I would like to find out what is the time taken for a vid to be generated for the user. What I want to achieve is for a Contact to be added, as well as add them to as List. Assuming that I have created these 3 functions, as well as always having the User’s email address:


I’d run hs_submit_form() to add the Contact, then try to get the vid of the User with their email using hs_get_contact_vid_by_email(), but I noticed that I got an empty response. Which causes hs_add_contact_to_list() to not do anything (returning {‘discarded’: [], ‘updated’: [], “invalidVids”:[], “invalidEmails”:[] } response).


Form submissions are processed asynchronously, and while it takes less than a second for that process, it’s not instant.

If you’re only looking up the contact to add them to a list, you should see if you could use a smart list to have the contact added automatically. Smart lists can automatically add contacts based on several criteria, including submitting a specific form or specific values for contact properties, so you may be able to get the contact added just by the data in the form submissions (or the submission to that form itself).


@dadams Got what you mean, and have been using the Smart Lists by filtering Contacts that have filled up that particular form. Awesome - Thank you so much for your help all these time! :slight_smile: