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.
Below, learn more about the following commonly asked questions:
- How do I manipulate forms with jQuery?
- How should I format timestamps for HubSpot's APIs?
- What do I need to know about API error messages?
- Do the HubSpot APIs support CORS / AJAX requests?
- How does HubSpot validate email addresses?
- How do I set multiple values for checkbox properties?
- Are there limits on contact records?
- How do I send transactional emails?
- How do I subscribe to API updates?
- How do I handle privacy and legal compliance when working with the HubSpot platform?
How do I manipulate forms using jQuery?
When you manipulate form input values using .
val() or .
prop(), you must trigger a change event using
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
How should I format timestamps for HubSpot's APIs?Time values are represented in ISO 8601 format in responses, but the APIs will accept either of two formats for date and time values:
- 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 date and time, the complete date 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). All times are represented in UTC, so the values will always use the UTC designator "Z."
- UNIX-formatted timestamps in milliseconds: timestamp values in milliseconds, which are represented in UTC time. For example, the timestamp value 1427997766000 translates to 02 Apr 2015 18:02:46 UTC, or April 2nd, 2015, 2:02:46 PM EDT (Eastern Daylight Saving Time).
Date and datetime properties in the HubSpot CRM
HubSpot has two types of CRM object properties for storing time:
date pickerproperties created in HubSpot) store the date—not the time.
dateproperties display the date they're set to, regardless of the time zone setting of the account or user. For
dateproperty values, it is recommended to use the ISO 8601 complete date format. If you use the UNIX timestamp format, you must use an EPOCH millisecond timestamp (i.e. the value must be set to midnight UTC for the date). For example, to represent May 1, 2015 in either format:
- IOS 8601: 2015-05-01
- EPOCH-millisecond timestamp: 1430438400000
Please note: if you're using a UNIX timestamp for a
date property and try to set a value that isn't midnight UTC, you'll receive an error.
datetimeproperties store both the date and time. Either timestamp format will be accepted. In HubSpot,
datetimeproperties 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. Because
date pickerproperties created in HubSpot are created as a
dateproperties, the only way to create a
datetimeproperty is via API. If your integration needs to store specific times, you can create custom
datetimeproperties using the property endpoints.
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
403when 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.
Do the HubSpot APIs support CORS / AJAX requests?
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, HubSpot places the following restrictions on email addresses:
- Local parts of the address cannot include quotation marks. (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).
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 (;).
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:
For the Forms endpoints, make sure that the semicolons are also URL encoded:
Are there limits on contact records?
HubSpot has a few limits in place regarding merged contact records and form submissions for contact records:
- 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.
- 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-submissionsdata 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 legal basis of processing in HubSpot
Under GDPR, companies need a legal reason to use and process contact data and must keep records of consent and evidence other legal purposes of processing.
Legal basis for processing contact's data contact property allows you to collect, track, and store legal 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.