Intercom

Authentication & Authorization

Credentials

• Intercom connects via OAuth 2.0 with Authorization Code Grant Flow.
• DataGrail owns a Intercom OAuth 2.0 App that provides the credentials to authenticate customers allowing the integration to connect by simply logging into their Intercom account with their admin credentials and accepting to install the app. See Intercom Connection Instruction.
• Intercom API uses authentication with an Access Token in the Authorization request header field (which uses the Bearer authentication scheme to transmit the Access Token).
• DataGrail uses Refresh Token Flow to periodically update Access Token after it expires to keep the connection alive.

Scopes

Intercom 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:

• Read and list users and companies
• Read one user and one company

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

Deletion

• Write users and companies

Responsible Data Discovery (RDD)

• Read and List Articles
• Read tickets
• Read conversations
• Read and List news items and newsfeeds
• Read events

Base URL

For customers who are using Regional Data Hosting, the base URI for the API Endpoints are listed below. This replaces the start of the URIs for each REST API endpoint, to connect to the specific regions:

• USA: https:​//api.intercom.io/
• Europe: https:​//api.eu.intercom.io
• Australia: https:​//api.au.intercom.io

All utilized endpoints in this specification are described with USA Regional Data Hosting.

Endpoints Utilized

• Request authorization:
  • GET https:​//app.intercom.io/oauth
• Get and refresh access token:
  • POST https:​//api.intercom.io/auth/eagle/token
• Verify connection:
  • GET https:​//api.intercom.io/me

Version

DataGrail integration currently uses Intercom REST API version 2.0.

Limits

• DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.
• 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:

• Search for contacts by the Data Subject email.
• Extract companies which the contact belongs to from the collected contact details.
• Fetch companies details the contact belongs to by the extracted URLs.
• Extract notes which have been added to the contact from the collected contact details.
• Fetch notes which have been added to the contact by the extracted URLs.
• You can edit which objects and fields you want to provide to the Data Subject via our Portal Requests:
  • DataGrail will exclude fields "author" and "body" from the collected notes, because these fields may contain personal data of another person.
  • For all other objects found, DataGrail will return all available fields.

Endpoints Utilized

• POST https​://api.intercom.io/contacts/search
• GET https​://api.intercom.io/companies/{company_id}
• GET https​://api.intercom.io/notes/{note_id}

note

DataGrail also supports the Direct Contact Access workflow for Intercom.

Deletion

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

• Search for contacts by the Data Subject email.
• Delete contacts by their unique identifiers.

Endpoints Utilized

• POST https​://api.intercom.io/contacts/search
• DELETE https​://api.intercom.io/contacts/contacts/{contact_id}

note

DataGrail supports the Direct Contact Deletion workflow for Intercom.

System Detection

DataGrail provides continuous system detection, delivering a real-time inventory of your data assets.

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

• Fetch a list of all data attributes belonging to a workspace contacts and companies.
• List all companies and collect custom attributes which are set for the company.
• List all contacts and collect custom attributes for updated contacts only.
• Search for multiple contacts by the value of their attributes

Endpoints Utilized

• GET https​://api.intercom.io/data_attributes
• GET https​://api.intercom.io/companies
• GET https​://api.intercom.io/contacts
• GET https​://api.intercom.io/contacts/search

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 Intercom objects:

• Contacts
• Articles
• Conversations
• News and Newsfeds
• Notes
• Data Events
• Tickets

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.intercom.io/contacts
• GET https​://api.intercom.io/contacts/{contact_id}/notes
• GET https​://api.intercom.io/articles
• GET https​://api.intercom.io/conversations
• GET https​://api.intercom.io/news/news_items
• GET https​://api.intercom.io/news/newsfeeds
• GET https​://api.intercom.io/events
• GET https​://api.intercom.io/tickets
• GET https​://api.intercom.io/tickets/{ticket_id}