FAQ

Get answers to frequently asked questions about HubSpot's APIs. For CMS development questions, visit their documentation. If you can't find what you're looking for, you can ask on our developer forum

How do I manipulate forms using jQuery?

When you manipulate form input values using .val() or .prop(), you must trigger a change event using change()  or  trigger('change') for the change to register correctly.

Because HubSpot forms are rendered after the DOM builds, you must either trigger the manipulation after the window loads or modify the embed to use the onFormReady parameter.

JavaScript
Update fields when page finishes loading:

$(window).load(function(){
    $('input[value="checkbox_1"]').prop('checked', true).change();
    $('input[name="firstname"]').val('Brian').change();     
});

Modified embed code to update fields when form builds:

hbspt.forms.create({ 
    portalId: 'XXXXXX',
    formId: 'aa8b5b4a-62ac-461b-a387-XXXXXXXXXXX',
    onFormReady: function($form, ctx){
   		$('input[value="checkbox_1"]').prop('checked', true).change();
    	$('input[name="firstname"]').val('Brian').change();   
   	}
  });

How should I format timestamps for HubSpot's APIs?

The HubSpot APIs accept two different formats for date and time values.

The first format is ISO 8601 formatted strings. Depending on the type of data, these will be one of two different formats:

  • For values that represent a specific date, the complete date format will be used: YYYY-MM-DD (e.g. 2020-02-29)
  • For values that represent a specific data and time, the complete data plus hours, minutes, seconds, and a decimal fraction of a second format will be used: YYYY-MM-DDThh:mm:ss.sTZD (e.g. 2020-02-29T03:30:17.000Z). Note that all times will be represented in UTC, so the values will always use the UTC designator "Z."

The second format is UNIX-formatted timestamps in milliseconds. Timestamp values will be treated as if they are set in UTC time. For example, the timestamp value 1427997766000 translates to April 2nd, 2015, 2:02:46 PM EDT (Eastern Daylight Saving Time) or 02 Apr 2015 18:02:46 UTC.

Time values will be represented with the ISO 8601 value in responses, but the APIs will accept either format.

Date and datetime properties in the HubSpot CRM

HubSpot has two types of CRM object properties for storing time: date and datetime.

Date properties (including date picker properties created in HubSpot) can only store the date—not the time. When setting date property values, we recommend using the ISO 8601 complete date format.

Examples:

  • 2015-05-01 would be used for May 1 2015. While it is possible to use a millisecond timestamp, the values must be set to midnight UTC for the desired date. 
  • 1430438400000 would be used for May 1 2015 (01 May 2015 00:00:00 UTC).

If you try to set a value that isn't midnight UTC, you'll receive an error. In HubSpot, date properties always display the specific date they're set to, regardless of the time zone setting of the account or user.

Datetime properties can store any time, so any valid date or date and time value using either format will be accepted. In HubSpot, datetime properties are displayed based on the time zone of the user viewing the record, so the value will be converted to the local time zone of the user.

The only way to create a datetime property is by using the APIs, as any date picker property created in HubSpot is created as a date property. If your integration needs to store specific times, we'd recommend creating custom datetime properties using the property endpoints for whichever CRM objects your integration works with.


What do I need to know about API error messages?

Unless specified otherwise, most HubSpot endpoints will return a 200 OK response upon success. Any endpoints returning a different status code will specify the returned response in its documentation.

In addition, HubSpot has several error responses that are common to multiple APIs:

  • 401 Unauthorized - Returned when the authentication provided is invalid. See our Authentication Overview for details on authenticating API requests.
  • 403 Forbidden - Returned when the authentication provided does not have the proper permissions to access the specific URL. As an example, an OAuth token that only has content access would get a 403 when accessing the Deals API (which requires contacts access).
  • 429 Too many requests - Returned when your account or app is over its API rate limits. Find suggestions on working within those limits here.
  • 502/504 timeouts - HubSpot has processing limits in place to prevent a single client from causing degraded performance, and these responses indicate that those limits have been hit. You'll normally only see these timeout responses when making a large number of requests over a sustained period. If you get one of these responses, you should pause your requests for a few seconds, then retry.

Aside from these general errors, HubSpot error responses are intended to be human-readable. Most endpoints don't return error codes, but return a JSON formatted response with details about the error. More details for endpoint-specific errors can be found on the documentation pages for the endpoint.

Note: The fields in the example response below should all be treated as optional in any error parsing. The specific fields included can vary between different APIs, so any error parsing should allow for specific fields to be missing from the response.

JSON
{"status":"error","message":"This will be a human readable message with details about the error.","errors":[{"message":"This will be a message with additional details about the error","in":"name"}],"category":"VALIDATION_ERROR","correlationId":"a43683b0-5717-4ceb-80b4-104d02915d8c"}

Do the HubSpot APIs support CORS / AJAX requests?

For the most part, the HubSpot APIs do not support cross-origin (CORS) AJAX requests. Making the request client-side using JavaScript would expose any authentication you're using for the request. In order to use JavaScript/AJAX, you would need to make the request (excluding any authentication) to an external server that could then add the needed authentication and make requests to HubSpot's APIs server-side.

The exceptions to this rule are:


How does HubSpot validate email addresses?

HubSpot validates email addresses used for any process that would create or update a contact record. This includes using the contacts endpoints to create or update a contact as well as form submissions or events.

These processes don't check the email address itself for validity (like an embedded form would), but rather its format. In addition to being valid according to RFC 2822, we place the following restrictions on email addresses:

  • We don't allow the local parts to be quoted. (e.g. "Test Email"@hubspot.com isn't valid)
  • The domain part must end in a valid TLD, as listed at https://data.iana.org/TLD/tlds-alpha-by-domain.txt (note that this is after handling unicode TLDs, so "user@email.삼성" is a valid email address).
  • When using the v3 Forms API, validation can be ignored by adding the skipValidation parameter to the request body and setting it to true.

How do I set multiple values for checkbox properties?

When setting multiple values for a checkox property, the values should be separated with a semicolon (;).
Example: 'value1;value2;value5'

When updating a record through the CRM object endpoints, the property value should be a single string with all of the values separated by semicolons:

{
  "properties":
    {
      "example_property": "value1;value3;value4"
    }
}

For the Forms endpoints, make sure that the semicolons are also URL encoded:

...&example_property=value1%3Bvalue2%3Bvalue4


Are there limits on contact records?

HubSpot has a few limits in place regarding merged contact records and form submissions for contact records:

  1. There's a limit of 250 linked identities per contact.
    • If you try to merge two contacts, and the resulting contact would have more than 250 identities, you will get an error.
  2. Contacts are limited to 1000 form submissions. Submissions that would take a contact over this limit will be dropped completely:
    • The form data will not update the contact record.
    • The submission itself will not show up for the contact record, either in the form-submissions data from the contacts endpoints or in the contact's timeline.
    • The submission won't be evaluated for list membership or workflows.
    • The submission won't appear in the submissions list for viewing the form in HubSpot.

If you're exceeding either of these limits because of testing, we'd recommend deleting the test contacts and creating a new test record. Using the same email address in the new contact won't restore the deleted contact, and any form submissions with the email will be associated to the new record.


How do I send transactional emails?

HubSpot supports two methods of sending transactional emails: the SMTP API and the Single-send API.

Using the SMTP API

The SMTP API doesn't directly send emails, but is only used to get login credentials for the HubSpot SMTP server. After you get a token and password using the SMTP API, you'll need to use those credentials to log into HubSpot's SMTP server and send the email over SMTP. The login details (hostname and port) for the SMTP server can be found on the documentation page. The email and links will be wrapped to support HubSpot's email tracking, but otherwise you will need to build the entirety of the email content.

Using the Single-send API

The Single-send API uses template emails created in the HubSpot email tool, along with a JSON formatted POST API to send emails. First, you'll need to create an email in HubSpot and select "Save for single-send API" when choosing the recipient.  After the email is created, you can use the API to send the email to a contact, setting the details for the recipient (including any contact or custom properties set up in the email) in the body of the API request.  More details for the format of that JSON request can be found on the documentation page.


How do I subscribe to API updates?

Updates to HubSpot's APIs and developer tools are made through our Developer Changelog.

You can use the form on the left to subscribe to updates. Select Instant for the frequency to get notifications as soon as they are announced. Otherwise, select one of the other frequencies to get a digest of updates at your chosen frequency.


How do I handle privacy and legal compliance when working with the HubSpot platform?

Tracking lawful basis of processing in HubSpot

Under GDPR, companies need a lawful reason to use and process contact data and must keep records of consent and evidence other lawful purposes of processing.

The Legal basis for processing contact's data contact property allows you to collect, track, and store lawful basis of processing via contract, legitimate interest, and/or consent for your HubSpot contacts.

When accessing contact data via the contacts endpoints, this property uses the name hs_legal_basis. As with any other contact property, any contact with this property set would be accessible through the API. The property can also be set or updated for contact records through the API.

However, the property options can't be modified through the API. They can only be updated from inside HubSpot, but it's possible to pull any custom options that may have been set for the property through the contact properties endpoints. Since individual HubSpot accounts may not use the default settings, using these endpoints to get the property options is recommended.

For more details about this property and how it might be used in HubSpot, please see this
knowledge base article.

Handling privacy compliant contact deletions

HubSpot users have the ability to permanently delete a contact record to comply with privacy laws. Please see this knowledge base article for more information.

You can subscribe to the contact.privacyDeletion subscription type to receive webhook notifications when a user performs a privacy compliant contact deletion. Please see the Webhooks Overview for more details on webhooks and handling these notifications.