Intercom integration summary

Stitch’s Intercom integration replicates data using the Intercom API (V2.5). Refer to the Schema section for a list of objects available for replication.

Intercom feature snapshot

A high-level look at Stitch's Intercom (v2) integration, including release status, useful links, and the features supported in Stitch.

STITCH
Release status

Released on December 13, 2022

Supported by

Stitch

Stitch plan

Standard

API availability

Available

Singer GitHub repository

singer-io/tap-intercom

REPLICATION SETTINGS
Anchor Scheduling

Supported

Advanced Scheduling

Supported

Table-level reset

Unsupported

Configurable Replication Methods

Unsupported

DATA SELECTION
Table selection

Supported

Column selection

Supported

Select all

Supported

TRANSPARENCY
Extraction Logs

Supported

Loading Reports

Supported

Connecting Intercom

Step 1: Add Intercom as a Stitch data source

  1. Sign into your Stitch account.
  2. On the Stitch Dashboard page, click the Add Integration button.

  3. Click the Intercom icon.

  4. Enter a name for the integration. This is the name that will display on the Stitch Dashboard for the integration; it’ll also be used to create the schema in your destination.

    For example, the name “Stitch Intercom” would create a schema called stitch_intercom in the destination. Note: Schema names cannot be changed after you save the integration.

Step 2: Define the historical replication start date

The Sync Historical Data setting defines the starting date for your Intercom integration. This means that:

  • For tables using Key-based Incremental Replication, data equal to or newer than this date will be replicated to your destination.
  • For tables using Full Table Replication, all data - including records that are older, equal to, or newer than this date - will be replicated to your destination.

Change this setting if you want to replicate data beyond Intercom’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.

Step 3: Create a replication schedule

In the Replication Frequency section, you’ll create the integration’s replication schedule. An integration’s replication schedule determines how often Stitch runs a replication job, and the time that job begins.

Intercom integrations support the following replication scheduling methods:

To keep your row usage low, consider setting the integration to replicate less frequently. See the Understanding and Reducing Your Row Usage guide for tips on reducing your usage.

Step 4: Authorize Stitch to access Intercom

Lastly, you’ll be directed to Intercom’s website to complete the setup.

List of permissions requested by Stitch to access Intercom

  1. If you aren’t already logged into Intercom, you’ll be prompted to do so.
  2. Next, a screen requesting access to Intercom will display. Note: Stitch will only ever read your data.
  3. Click Connect.
  4. After the authorization process successfully completes, you’ll be redirected back to Stitch.
  5. Click All Done.

Step 5: Set objects to replicate

The last step is to select the tables and columns you want to replicate. Learn about the available tables for this integration.

Note: If a replication job is currently in progress, new selections won’t be used until the next job starts.

For Intercom integrations, you can select:

  1. Individual tables and columns

  2. All tables and columns

Click the tabs to view instructions for each selection method.

  1. In the integration’s Tables to Replicate tab, locate a table you want to replicate.
  2. To track a table, click the checkbox next to the table’s name. A blue checkmark means the table is set to replicate.

  3. To track a column, click the checkbox next to the column’s name. A blue checkmark means the column is set to replicate.

  4. Repeat this process for all the tables and columns you want to replicate.
  5. When finished, click the Finalize Your Selections button at the bottom of the screen to save your selections.
  1. Click into the integration from the Stitch Dashboard page.
  2. Click the Tables to Replicate tab.

  3. In the list of tables, click the box next to the Table Names column.
  4. In the menu that displays, click Track all Tables and Fields:

    The Track all Tables and Fields menu in the Tables to Replicate tab

  5. Click the Finalize Your Selections button at the bottom of the page to save your data selections.

Initial and historical replication jobs

After you finish setting up Intercom, its Sync Status may show as Pending on either the Stitch Dashboard or in the Integration Details page.

For a new integration, a Pending status indicates that Stitch is in the process of scheduling the initial replication job for the integration. This may take some time to complete.

Free historical data loads

The first seven days of replication, beginning when data is first replicated, are free. Rows replicated from the new integration during this time won’t count towards your quota. Stitch offers this as a way of testing new integrations, measuring usage, and ensuring historical data volumes don’t quickly consume your quota.


Intercom table reference

Replication Method :

Full Table

Primary Key :

id

API endpoint :

List all admins

The admins table lists info about the admins in your Intercom account. An admin is a user, or teammate, in your Intercom account.

id
INTEGER

The admin ID.

avatar
STRING

The URL to the admin’s avatar.

away_mode_enabled
BOOLEAN

Indicates if the admin is currently set in away mode.

away_mode_reassign
BOOLEAN

Indicates if the admin is set to automatically reassign new conversations to the app’s default inbox.

email
STRING

The email address of the admin.

has_inbox_seat
BOOLEAN

Indicates if the admin has a paid inbox seat to restrict/allow features.

job_title
STRING

The job title of the admin.

name
STRING

The name of the admin.

team_ids
ARRAY

The IDs of the teams the admin is a member of.

value
INTEGER

admins (table), team_ids (attribute)

type
STRING

This will be admin.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Scroll over all companies

The companies table contains info about companies that use your Intercom product.

Custom attributes

If applicable, Stitch will replicate custom fields related to companies in Intercom.

Limitations

Intercom’s API limits the number of simultaneous requests a single Intercom app, or connection, can make to the Scroll over all companies endpoint. Stitch uses this endpoint to replicate company data. Currently, only one request can occur at a time.

If multiple connections exist and they attempt to use this endpoint at the same time, only the connection who made the request first will succeed.

This means that if Stitch attempts to extract data when another connection is using the endpoint, Extraction will fail and an error will surface in the Extraction Logs.

To prevent or minimize this issue, we recommend limiting the number of connections a single workspace has or scheduling extraction jobs in Stitch around your other connections’ usage.

id
STRING

The Intercom-generated company ID.

updated_at
DATE-TIME

The time the company was last updated.

company_id
STRING

The ID for the company, as defined by you.

created_at
DATE-TIME

The time the company was added to Intercom.

custom_attributes
OBJECT

If applicable, the custom attributes you’ve applied to the company.

industry
STRING

The industry the company operates in.

last_request_at
DATE-TIME

The time the company last recorded making a request.

monthly_spend
INTEGER

The amount of revenue the company generates for your business.

name
STRING

The name of the company.

plan
OBJECT

The name of the plan associated with the company.

id
STRING

The plan ID.

name
STRING

The name of the plan.

type
STRING

This will be plan.

companies (table), plan (attribute)

remote_created_at
DATE-TIME

The time the company was created, as a Unix timestamp.

segments
ARRAY

A list of segments within a company.

id
STRING

The segment ID.

companies (table), segments (attribute)

session_count
INTEGER

The number of recorded sessions for the company.

size
INTEGER

The number of employees in the company.

tags
ARRAY

A list of tags within a company.

id
STRING

The tag ID.

companies (table), tags (attribute)

type
STRING

This will be company.

user_count
INTEGER

The number of users in the company.

website
STRING

The URL for the company’s website.


company_attributes

Replication Method :

Full Table

Primary Key :

_sdc_record_hash

API endpoint :

List all data attributes

The company_attributes lists data attributes for a specified company in your Intercom account.

_sdc_record_hash
STRING

Stitch-generated SHA 256 hash that includes the values of the id, name, and description columns.

name
STRING

The name of the attribute.

admin_id
INTEGER

The ID of the admin that created the attribute.

api_writable
BOOLEAN

Indicates if the attribute can be updated via Intercom’s API.

archived
BOOLEAN

Indicates if the attribute is archived.

created_at
DATE-TIME

The time the attribute was created.

custom
BOOLEAN

data_type
STRING

The type of data stored for the attribute. Possible values are:

  • string
  • fixnum
  • float
  • boolean
  • date
  • options

description
STRING

The description for the attribute.

full_name
STRING

id
INTEGER

label
STRING

The name of the attribute.

options
ARRAY

The pre-defined options for the attribute.

value
VARIES

company_attributes (table), options (attribute)

type
STRING

This will be data_attribute.

ui_writable
BOOLEAN

Indicates if the attribute can be updated via Intercom’s UI.

updated_at
DATE-TIME

The last time the attribute was updated.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List all segments

The company_segments table contains information about company segments in your Intercom account.

id
STRING

The company segment ID.

updated_at
DATE-TIME

The time the company segment was last updated.

count
INTEGER

created_at
DATE-TIME

The time the company segment was created.

name
STRING

The name of the segment.

type
STRING

The value of this field will be segment.

person_type
STRING

Type of the record: user or lead.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List all contacts

The contacts table contains info about users and leads in your Intercom account.

Custom attributes

If applicable, Stitch will replicate custom fields related to contacts in Intercom.

id
STRING

The contact ID.

updated_at
DATE-TIME

The time the contact was last updated.

android_app_name
STRING

The name of the Android app the contact is using, if applicable.

android_app_version
STRING

The version of the Android app the contact is using, if applicable.

android_device
STRING

The Android device the contact is using, if applicable.

android_last_seen_at
DATE-TIME

The last time the contact used the Android app, if applicable.

android_os_version
STRING

The version of the Android OS the contact is using, if applicable.

android_sdk_version
STRING

The version of the Android SDK the contact is using, if applicable.

avatar
STRING

browser
STRING

The name of the browser the contact is using.

browser_language
STRING

The language set by the browser the contact is using.

browser_version
STRING

The version of the browser the contact is using.”

companies
ARRAY

Details about the company the contact is associated with.

items
OBJECT

Details about the company the contact is associated with.

id
STRING

The Intercom-defined company ID.

contacts (table), items (attribute)

has_more
BOOLEAN

total_count
INTEGER

type
STRING

This will be list.

url
STRING

contacts (table), companies (attribute)

created_at
DATE-TIME

The time the contact was created.

custom_attributes
OBJECT

The custom attributes set for the contact.

email
STRING

The email associated with the lead.

external_id
STRING

The unique ID for the contact.

has_hard_bounced
BOOLEAN

Indicates whether the contact has had an email sent to them hard bounce.

ios_app_name
STRING

The name of the iOS app the contact is using, if applicable.

ios_app_version
STRING

The version of the iOS app the contact is using, if applicable.

ios_device
STRING

The iOS device the contact is using, if applicable.

ios_last_seen_at
DATE-TIME

The last time the contact used the iOS app, if applicable.

ios_os_version
STRING

The version of the iOS OS the contact is using, if applicable.

ios_sdk_version
STRING

The version of the iOS SDK the contact is using, if applicable.

language_override
STRING

The preferred language setting for the contact.

last_contacted_at
DATE-TIME

The time when the contact was last messaged.

last_email_clicked_at
DATE-TIME

The time when the contact last clicked a link in an email sent to them, as a Unix timestamp.

last_email_opened_at
DATE-TIME

The time when the contact last opened an email sent to them, as a Unix timestamp.

last_replied_at
DATE-TIME

The time when the contact last sent a message, as a Unix timestamp.

last_seen_at
DATE-TIME

The time the contact was last seen, as a Unix timestamp.

location
OBJECT

Details about the contact’s location.

city
STRING

The contact’s city.

continent_code
STRING

The contact’s continent code.

country
STRING

The contact’s country.

country_code
STRING

The contact’s country code.

region
STRING

The contact’s region.

type
STRING

This will be location.

contacts (table), location (attribute)

marked_email_as_spam
BOOLEAN

Indicates if the contact has marked an email sent to them as spam.

name
STRING

The name of the lead.

notes
OBJECT

The notes that have been added to the contact.

data
ARRAY

The notes that have been added to the contact.

id
STRING

The note ID.

type
STRING

This will be note.

url
STRING

contacts (table), data (attribute)

has_more
BOOLEAN

total_count
INTEGER

type
STRING

This will be list.

url
STRING

contacts (table), notes (attribute)

os
STRING

The operating system the contact is using.

owner_id
INTEGER

The ID of the admin that has been assigned account ownership of the contact.

phone
STRING

The phone number associated with the lead.

role
STRING

The role of the contact. This will be either lead or user.

signed_up_at
DATE-TIME

The time when a contact signed up, as a Unix timestamp.

social_profiles
OBJECT

Details about the social profiles the lead is associated with.

data
ARRAY

name
STRING

The name of the social service. Ex: facebook

type
STRING

This will be social_profile.

url
STRING

The URL of the social profile.

contacts (table), data (attribute)

type
STRING

contacts (table), social_profiles (attribute)

tags
ARRAY

Details about the tags applied to the contact.

items
OBJECT

Details about the tags applied to the contact.

id
STRING

The ID of the tag.

contacts (table), items (attribute)
contacts (table), tags (attribute)

type
STRING

This will be contact.

unsubscribed_from_emails
BOOLEAN

Indicates if the contact has unsubscribed from emails.

workspace_id
STRING

The ID of the workspace the contact is associated with.


contact_attributes

Replication Method :

Full Table

Primary Key :

_sdc_record_hash

API endpoint :

List all data attributes

The contact_attributes table contains information about contact attributes in your Intercom account.

_sdc_record_hash
STRING

Stitch-generated SHA 256 hash that includes the values of the id, name, and description columns.

name
STRING

The name of the attribute.

admin_id
INTEGER

The ID of the admin that created the attribute.

api_writable
BOOLEAN

Indicates if the attribute can be updated via Intercom’s API.

archived
BOOLEAN

Indicates if the attribute is archived.

created_at
DATE-TIME

The time the attribute was created.

custom
BOOLEAN

data_type
STRING

The type of data stored for the attribute. Possible values are:

  • string
  • fixnum
  • float
  • boolean
  • date
  • options

description
STRING

The description for the attribute.

full_name
STRING

id
INTEGER

label
STRING

The name of the attribute.

options
ARRAY

The pre-defined options for the attribute.

value
VARIES

contact_attributes (table), options (attribute)

type
STRING

This will be data_attribute.

ui_writable
BOOLEAN

Indicates if the attribute can be updated via Intercom’s UI.

updated_at
DATE-TIME

The last time the attribute was updated.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List all conversations

The conversations table contains info about user conversations in your Intercom account.

id
STRING

The conversation ID.

updated_at
DATE-TIME

The time that the conversation was last updated.

assignee
OBJECT

Details about the admin or team assigned to the conversation.

email
STRING

id
STRING

The ID of the admin or team assigned to the conversation message.

Depending on the type, this will be a foreign key to either the admins or teams table.

name
STRING

type
STRING

conversations (table), assignee (attribute)

contacts
ARRAY

Information about the contacts associated with the conversation.

id
STRING

The contact ID.

type
STRING

conversations (table), contacts (attribute)

conversation_message
OBJECT

A list of message details.

attachments
ARRAY

Details about the attachments, if any, that are a part of the conversation message.

url
STRING

The attachment URL.

name
STRING

The name of the attachment. Ex: image001.png, presentation.pdf

content_type
STRING

The content type of the attachment. Ex: image/png, application/pdf

height
INTEGER

For image attachments, the height of the image.

width
INTEGER

For image attachments, the width of the image.

filesize
INTEGER

The file size of the attachment.

type
STRING

The value of this field will be upload.

conversations (table), attachments (attribute)

author
OBJECT

Details about the user that created the conversation message.

id
STRING

The ID of the user who created the conversation message.

Depending on the author’s type, this will be a foreign key to either the admins or contacts table.

type
STRING

The type of user that created the conversation message. Possible values are:

  • user
  • lead
  • admin
conversations (table), author (attribute)

body
STRING

The conversation message body, which may contain HTML. This is the body of the message that started the conversation.

delivered_as
STRING

id
STRING

The ID of the conversation message.

subject
STRING

The conversation message subject, or the subject of the message that started the conversation.

type
STRING

The type of the conversation message. Possible values are:

  • conversation
  • push
  • facebook
  • twitter
  • email

url
STRING

The URL where the conversation was started. For Twitter, Email, and Bots, this will be null.

conversations (table), conversation_message (attribute)

conversation_rating
OBJECT

Details about the rating for the conversation.

created_at
DATE-TIME

The time that the conversation being rated was created.

contact
OBJECT

Details about the contact who rated the conversation.

id
STRING

The user or lead ID.

type
STRING

This can be either user or lead.

conversations (table), contact (attribute)

rating
INTEGER

The rating, between 1 and 5, for the conversation.

remark
STRING

A remark about the rating, if any.

teammate
OBJECT

The ID of the teammate associated with the conversation when it was rated.

id
INTEGER

The ID of the teammate.

type
STRING

The type of the teammate.

conversations (table), teammate (attribute)
conversations (table), conversation_rating (attribute)

created_at
DATE-TIME

The time the conversation was created.

customers
ARRAY

Details about the customers involved in the conversation.

id
STRING

The customer ID.

type
STRING

The type of the customer. This will be either lead or user.

conversations (table), customers (attribute)

first_contact_reply
OBJECT

Details about the contact’s first reply to the conversation.

created_at
DATE-TIME

type
STRING

url
STRING

conversations (table), first_contact_reply (attribute)

open
BOOLEAN

Indicates whether a conversation is open/snoozed (true) or closed (false).

priority
STRING

The conversation’s priority level.

read
BOOLEAN

Indicates whether a conversation has been read.

sent_at
DATE-TIME

sla_applied
OBJECT

Information about the service-level agreement applied to the conversation.

sla_name
STRING

sla_status
STRING

conversations (table), sla_applied (attribute)

snoozed_until
DATE-TIME

If set, this is the time in the future when the conversation will be marked as open.

source
OBJECT

attachments
ARRAY

author
OBJECT

email
STRING

id
STRING

The ID of the user who created the source.

Depending on the author’s type, this will be a foreign key to either the admins or contacts table.

name
STRING

type
STRING

conversations (table), author (attribute)

body
STRING

delivered_as
STRING

id
STRING

redacted
BOOLEAN

subject
STRING

type
STRING

url
STRING

conversations (table), source (attribute)

state
STRING

The current state of the conversation. Possible values are:

  • open
  • closed
  • snoozed

statistics
OBJECT

Details on conversation statistics.

count_assignments
INTEGER

count_conversation_parts
INTEGER

count_reopens
INTEGER

first_admin_reply_at
DATE-TIME

first_assignment_at
DATE-TIME

first_close_at
DATE-TIME

first_contact_reply_at
DATE-TIME

last_admin_reply_at
DATE-TIME

last_assignment_admin_reply_at
DATE-TIME

last_assignment_at
DATE-TIME

last_close_at
DATE-TIME

last_closed_by

id
STRING

name
STRING

email
STRING

type
STRING

conversations (table), last_closed_by (attribute)

last_closed_by_id
INTEGER

last_contact_reply_at
DATE-TIME

median_time_to_reply
INTEGER

time_to_admin_reply
INTEGER

time_to_assignment
INTEGER

time_to_first_close
INTEGER

time_to_last_close
INTEGER

type
STRING

conversations (table), statistics (attribute)

tags
ARRAY

Details about the tags applied to the conversation.

id
STRING

The tag ID.

applied_at
DATE-TIME

The time the tag was applied.

applied_by
OBJECT

Details about the admin that applied the tag.

id
INTEGER

The admin ID.

type
STRING

This will be tag.

conversations (table), applied_by (attribute)

name
STRING

The name of the tag.

type
STRING

This will be tags.list.

conversations (table), tags (attribute)

teammates
OBJECT

Information about team members.

admins
ARRAY

The admin IDs of the team members associated with the conversation.

id
STRING

The admin ID.

type
STRING

conversations (table), admins (attribute)

type
STRING

conversations (table), teammates (attribute)

type
STRING

This will be conversation.

user
OBJECT

A list of users associated with the conversation.

id
STRING

The user ID.

type
STRING

conversations (table), user (attribute)

waiting_since
DATE-TIME

The last time a contact responded to an admin. In other words, the time a customer started waiting for a response. This will be null if last reply is from an admin.

title
STRING

admin_assignee_id
INTEGER

team_assignee_id
INTEGER

custom_attributes
OBJECT

issue_type
STRING

priority
STRING

conversations (table), custom_attributes (attribute)

conversation_parts

Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

Retrieve a conversation

The conversation_parts table lists the individual parts of conversations in your Intercom account.

Note: When this table is replicated, all conversation parts associated with an updated conversation will be replicated.

id
STRING

The conversation part ID.

assigned_to
STRING

The ID of the admin that the conversation part is assigned to.

attachments
ARRAY

Details about the attachments, if any, that are a part of the conversation part.

url
STRING

The attachment URL.

name
STRING

The name of the attachment. Ex: image001.png, presentation.pdf

content_type
STRING

The content type of the attachment. Ex: image/png, application/pdf

height
INTEGER

For image attachments, the height of the image.

width
INTEGER

For image attachments, the width of the image.

filesize
INTEGER

The file size of the attachment.

type
STRING

The value of this field will be upload.

conversation_parts (table), attachments (attribute)

author
OBJECT

Details about the admin or user that created the conversation part.

id
STRING

The ID of the admin or end-user that created the conversation part.

Depending on the author’s type, this will be a foreign key to either the admins or contacts table.

type
STRING

The type of user that created the conversation part.

conversation_parts (table), author (attribute)

body
STRING

The HTML-encoded body of the conversation part.

conversation_created_at
DATE-TIME

The time the parent conversation associated with the part was created.

conversation_id
STRING

The ID of the conversation associated with the part.

conversation_total_parts
INTEGER

The total number of conversation parts associated with the parent conversation.

conversation_updated_at
DATE-TIME

The time the parent conversation associated with the part was last updated.

created_at
DATE-TIME

The time the conversation part was created.

external_id
STRING

notified_at
DATE-TIME

The time the user was notified with the conversation part.

part_type
STRING

The type of the conversation part.

redacted
BOOLEAN

Indicates whether or not a conversation part has been redacted.

type
STRING

This will be conversation_part.

updated_at
DATE-TIME

The time the conversation part was updated.


Replication Method :

Key-based Incremental

Replication Key :

updated_at

Primary Key :

id

API endpoint :

List all segments

The segments table contains information about segments within your Intercom account.

id
STRING

The segment ID.

updated_at
DATE-TIME

The time the segment was last updated.

count
INTEGER

The number of items in the segment.

created_at
DATE-TIME

The time the segment was created.

name
STRING

The name of the segment.

person_type
STRING

The type of the record: user or lead.

type
STRING

This will be segment.


Replication Method :

Full Table

Primary Key :

id

API endpoint :

List all tags

The tags table contains information about tags within your Intercom account.

id
INTEGER

The tag ID.

name
STRING

The name of the tag.

type
STRING

This will be tag.


Replication Method :

Full Table

Primary Key :

id

API endpoint :

List all teams

The teams table contains information about teams in your Intercom account.

id
INTEGER

The team ID.

admin_ids
ARRAY

The admins that belong to the team.

id
STRING

The admin ID.

teams (table), admin_ids (attribute)

name
STRING

The name of the team.

type
STRING

This will be team.



Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.