HubSpot

Authentication & Authorization

Credentials

• HubSpot connects via OAuth 2.0 with Authorization Code Grant Flow.
• DataGrail owns a HubSpot OAuth 2.0 App that provides the credentials to authenticate customers allowing the integration to connect by simply logging into their HubSpot account with their admin credentials and accepting to install the app. See HubSpot Connection Instruction.
• DataGrail uses Refresh Token Flow to periodically update Access Token after it expires to keep the connection alive.

Scopes

HubSpot API requires specific scopes that need to be approved by the customer in order to grant DataGrail read/write on certain objects necessary to complete privacy requests:

The next scopes are required and should be set to connect DataGrail integration:

• oauth
• crm.objects.contacts.read

Additionally, depending on the required integration capabilities, DataGrail requires the following scopes to be set:

Access

• content (optional)
• crm.objects.deals.read
• crm.lists.read
• sales-email-read (optional)

Deletion

• content (optional)
• crm.objects.deals.read
• crm.lists.read
• sales-email-read (optional)
• crm.objects.contacts.write

System Detection

• crm.schemas.contacts.read
• crm.schemas.companies.read (optional)
• tickets (optional)
• e-commerce (optional)

Responsible Data Discovery (RDD)

• content (optional)
• crm.objects.custom.read (optional)
• sales-email-read (optional)

Endpoints Utilized

• Request authorization:
  • GET https​://app.hubspot.com/oauth/authorize
• Get and refresh access token:
  • POST https​://api.hubapi.com/oauth/v1/token
• Verify authentication:
  • GET https​://api.hubapi.com/integrations/v1/me
• Verify authorization (scopes):
  • GET https​://api.hubapi.com/oauth/v1/access-tokens/{token}

Version

DataGrail integration currently uses HubSpot API version 3 (v3) and some specific endpoints versions 1 (v1) and 2 (v2).

Limits

• DataGrail uses throttling rules to avoid rates faster than 50 requests per 10 sec and 125000 requests per day.
• Additionally, DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

Access

For an access request, DataGrail will take the following actions:

• Fetch contact information
• Fetch calls information
• Fetch emails information
• Fetch meetings information
• For all objects found, DataGrail will return a list of collected fields. Customer can edit which objects and fields he wants to provide to the Data Subject via our Portal Requests.

Endpoints Utilized

• POST https​://api.hubapi.com/crm/v3/objects/contacts/search
• GET https​://api.hubapi.com/crm/v3/objects/contacts/:contact_id/associations/calls
• GET https​://api.hubapi.com/crm/v3/objects/contacts/:contact_id/associations/emails
• GET https​://api.hubapi.com/crm/v3/objects/contacts/:contact_id/associations/meetings

note

DataGrail also supports the Direct Contact Access workflow for HubSpot.

Deletion

For a deletion request, DataGrail will take the following actions:

• Run access flow described above.
• Permanently delete a Contact and all associated content owned by the person with the Data Subject email (and selected to delete).

Endpoints Utilized

• POST https​://api.hubapi.com/crm/v3/objects/contacts/gdpr-delete

note

DataGrail also supports the Direct Contact Deletion workflow for HubSpot.

System Detection

DataGrail reads objects properties and recently updated contacts to detect the new systems added in your HubSpot.

For an system detection requests, DataGrail will take the following actions:

• Fetch properties for the next objects:
  • contacts
  • tickets
  • products
  • line_items
  • companies
• Get recently updated and created contacts.
• Get a contact profile by vid for all recently updated or created contacts.

Endpoints Utilized

• GET https​://api.hubapi.com/properties/v1/contacts/properties
• GET https​://api.hubapi.com/properties/v2/tickets/properties
• GET https​://api.hubapi.com/properties/v2/products/properties
• GET https​://api.hubapi.com/properties/v2/line_items/properties
• GET https​://api.hubapi.com/properties/v1/companies/properties
• GET https​://api.hubapi.com/contacts/v1/lists/recently_updated/contacts/recent
• GET https​://api.hubapi.com/contacts/v1/contact/vid/{vid}/profile

Responsible Data Discovery

Data discovery is based on the principle of finding any and all personal data that's stored in a data system.

Currently, DataGrail integration discovery the next HubSpot objects:

• contacts
• emails
• deals
• notes
• tasks
• calls
• meetings
• communications
• postal_mail
• custom objects detected via retrieving existing custom objects.

For discovery requests, DataGrail will take the following actions:

• Count number of all records for each of supported objects.
• Fetch records examples for each of the supported object.
• Sampling data for the next analysis and classification.

Endpoints Utilized

• GET https​://api.hubapi.com/crm/v3/schemas
• POST https​://api.hubapi.com/crm/v3/objects/{object_name}/search
• GET https​://api.hubapi.com/properties/v2/{object_name}/properties
• GET https​://api.hubapi.com/crm/v3/objects/{object_name}