Access and manage sensitive data (BETA)

With sensitive data properties, HubSpot users in Enterprise accounts can store certain types of sensitive data and use the data in HubSpot tools. For example, you can create a Passport Number property and filter contacts in a list based on its values. Refer to the sensitive data terms page to understand which types of sensitive data you can store and which HubSpot tools can access sensitive data.

Existing HubSpot APIs and apps will continue to work as expected, but if you have an app that needs access to sensitive data, you must update the app’s scopes and require app users to authorize and install the app. Once your app gains access, you can use the properties and object APIs to view sensitive data property definitions and view or update sensitive data property values for contacts, companies, deals, tickets, and custom objects.

For an app to access sensitive data, it must have the sensitive scopes for each applicable object. For example, if your app needs to read and update sensitive data on companies and contacts, you’ll need to add the company and contact read and write sensitive scopes. The sensitive scopes are:

• crm.objects.contacts.sensitive.read
• crm.objects.contacts.sensitive.write
• crm.objects.companies.sensitive.read
• crm.objects.companies.sensitive.write
• crm.objects.deals.sensitive.read
• crm.objects.deals.sensitive.write
• crm.objects.custom.sensitive.read
• crm.objects.custom.sensitive.write
• tickets.sensitive (Both read and write access)

The process for gaining access to sensitive data scopes depends on whether you have a private or public app.

For private apps, you can add the scopes in your private app settings.

• In your HubSpot account, click the settings icon in the top navigation bar.
• In the left sidebar menu, navigate to Integrations > Private Apps.
• On the private app, click Edit.

• Click the Scopes tab.
• Select the checkboxes of the sensitive scopes you want to add.

• In the top right, click Commit changes.

Your private app's access token will immediately have access to read and/or write sensitive data properties on the selected objects.

For public apps, you’ll need to request access to specific sensitive scopes from HubSpot’s Ecosystem Quality team. If approved, the team will allowlist the sensitive scopes to test your app and will help you publish your app with the required scopes following a period of testing and compliance checks. You’ll then need to notify app users of the change and request re-authorization of your app.

Navigate to this page to view the full process and fill out the form to request sensitive data access for public apps. 

Once the sensitive scopes have been added to your app, you’ll need to send authorization URLs to app users so they can authorize and install the app, granting access to sensitive data scopes. If they’re existing users of the app, they’ll need to reauthorize with the updated scopes for sensitive data access to apply. 

Once you’ve notified your app users, a Super admin in their account will need to:

• Click the authorization URL with sensitive data scopes.
• Select the account into which to install the app. The HubSpot account must have an Enterprise subscription to access sensitive data functionality.
• Review the updated list of scopes, then click Connect App to install.

Once your app has access to sensitive data, you can use the following APIs to manage sensitive data

• Properties API: retrieve sensitive data property information.
• Object APIs (Contacts, Companies, Deals, Tickets, Custom objects): retrieve or update sensitive data property values.
• CRM Search V3 API: search for records with values for sensitive data properties.
• Forms API:  send form submissions containing sensitive data. 
• Webhooks API: create propertyChange event type webhook subscriptions for contact, company, deal, and ticket sensitive data properties.

You can use the properties API to view sensitive data property definitions and schema information. At this time, you cannot create, update, or delete sensitive data properties via API.

• To retrieve all sensitive data properties, include the dataSensitivity query parameter with the value sensitive. This returns all sensitive data properties for the specified object. If you don't include this parameter when retrieving properties, only non-sensitive properties will be returned. For example, to retrieve all contact properties that store sensitive data, make a GET request to /crm/v3/properties/contacts?dataSensitivity=sensitive.
• To retrieve an individual property, make a GET request to /crm/v3/properties/{objectType}/{propertyName}. If a property contains sensitive data, in the response, the dataSensitivity property will have the value sensitive. If it’s not a sensitive data property, the value will be non_sensitive.

For example, if you you have a Passport Number sensitive data property, when you retrieve it, your response would look like:

You can retrieve a record’s value for a sensitive data property. To do this, make a GET request to /crm/v3/objects/{object}/{recordId} and include the sensitive data property in your query parameters.

For example, to retrieve a contact’s Passport Number value, your request URL would look like: https://api.hubspot.com/crm/v3/objects/contacts/1234567?properties=passport_number.

You can use the object APIs to create or edit records to set values for sensitive data properties.

• To create a record and set a value for a sensitive data property, make a POST request to /crm/v3/objects/{object}. In your request body, include the required properties and the sensitive data property. 
• To update a record’s value for a sensitive data property, make a PATCH request to /crm/v3/objects/{object}/{objectId}. In your request body, include the sensitive data property with the new value. To clear the value, set the value to an empty string in your request body.

If you wanted to update the property’s value later on, your request would look like:

If your app has the sensitive data scopes, you can use the V3 CRM search API to search for records with values for sensitive data properties. To do so, make a POST request to /crm/v3/objects/{object}/search and include the sensitive data properties you want to search for.

For example, the following search would return contacts with their first name, last name, and passport number values:

To send form submissions containing sensitive data to HubSpot, make a POST request to https://api.hsforms.com/submissions/v3/integration/secure/submit/{HubID}/:formGuid. Learn more about using this endpoint..

This is currently the only forms submission API endpoint that can be used with sensitive data because it supports authentication. Any other requests to the forms API will result in an error or hide sensitive data values.

You can create propertyChange event type webhook subscriptions for sensitive data properties on contacts, companies, deals, and tickets. 

For non-sensitive property propertyChange events, the webhook payload has the new value in the propertyValue field.  For sensitive property propertyChange events, the webhook payload will have the propertyValue set as "REDACTED". To view the value, you'll need to retrieve the record's value for the sensitive data property.

For example, a webhook payload for a sensitive property propertyChange event contact subscription would look like the following:

The following errors and redactions are expected:

• If you don’t have the required scope to read or update sensitive data for a given object, you’ll receive a 403 Forbidden error when you make a request containing a sensitive data property to that object's API.
• Sensitive data access is only supported for the V3 properties, object, CRM search, and forms APIs.
  • If you use legacy versions of the properties and object APIs, your request will appear successful, but sensitive data values won't be updated and will be hidden in the response body.
  • If you use legacy versions of the CRM search API, you'll receive a 403 Forbidden error citing support in version 3 or later.
  • If you use the unauthorized form submission API, you'll receive a 403 Forbidden error. If you try to retrieve form submissions containing sensitive data, the submissions will be returned but the sensitive data properties and their values will be hidden.