Help Scout integration summary

Stitch’s Help Scout integration replicates data using the Help Scout Mailbox API 2.0. Refer to the Schema section for a list of objects available for replication.

Help Scout feature snapshot

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

STITCH
Release status

Released on July 30, 2019

 Supported by

Stitch
Stitch plan

Standard

 API availability

Available
Singer GitHub repository

singer-io/tap-helpscout
REPLICATION SETTINGS
Anchor Scheduling

Supported

 Advanced Scheduling

Unsupported
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 Help Scout

Help Scout setup requirements

To set up Help Scout in Stitch, you need:

  • An active, invited Help Scout user. The Help Scout user setting up the integration in Stitch must be active and invited in Help Scout.

    To verify a user’s status, click Manage > Users in Help Scout.

Step 1: Add Help Scout 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 Help Scout 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 Help Scout” would create a schema called stitch_help_scout 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 Help Scout 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 Help Scout’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

When finished, click the Authorize button to continue.

Step 4: Authorize Stitch to access Help Scout

  1. After you click Authorize in Stitch, you’ll be prompted to sign into your Help Scout account. Enter your Help Scout credentials and click Log in.
  2. On the next page, click the Authorize button to continue.
  3. After the authorization process is successfully completed, you’ll be directed back to Stitch.
  4. 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 Help Scout 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 Help Scout, 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.

Help Scout table reference

conversations

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

List conversations

The conversations table contains info about the conversations in your Help Scout mailbox. Stitch will replicate all conversations, including active, closed, open, pending, and spam.

Note: If custom fields are available, Stitch will replicate them.

conversations table schema

id
INTEGER

The conversation ID.

Reference:

user_updated_at
DATE-TIME

The UTC time when the last user update occurred; equal to customerWaitingSince if a no user action since the last customer action.

updated_at
DATE-TIME

The UTC time when the last update occurred; equal to the maximum date between customerWaitingSince and userUpdatedAt.

assignee
OBJECT

Details about the assignee of the conversation.

Click to expand assignee

email
STRING

The assignee’s email address.

first
STRING

The assignee’s first name.

id
INTEGER

The assignee’s user ID.

Reference:

last
STRING

The assignee’s last name.

photo_url
STRING

The URL of the assignee’s photo, if one exists.

type
STRING

The user type. Possible values are:

  • team
  • user
conversations (table), assignee (attribute)

bcc
ARRAY

A list of emails that have been BCC’d on the conversation.

Click to expand bcc

value
STRING

The email that was BCC’d on the conversation.
conversations (table), bcc (attribute)

cc
ARRAY

A list of emails that have been CC’d on the conversation.

Click to expand cc

value
STRING

The email that was CC’d on the conversation.
conversations (table), cc (attribute)

closed_at
DATE-TIME

The UTC time when the conversation was closed.

closed_by
INTEGER

The ID of the Help Scout user that closed the conversation.

Reference:

created_at
DATE-TIME

The UTC time when the conversation was created.

created_by
OBJECT

Details about the user who created the conversation.

Click to expand created_by

email
STRING

The user’s email address.

first
STRING

The user’s first name.

id
INTEGER

The user’s user ID.

Reference:

last
STRING

The user’s last name.

photo_url
STRING

The URL of the user’s photo, if one exists.

type
STRING

The user type. Possible values are:

  • team
  • user
conversations (table), created_by (attribute)

custom_fields
ARRAY

Custom fields associated with the conversation.

Click to expand custom_fields

id
NUMBER

The custom field’s ID.

name
STRING

The name of the custom field.

value
STRING

The value of the custom field.

text
STRING

The text value of the custom field.
conversations (table), custom_fields (attribute)

customer_waiting_since
OBJECT

Details about when the conversation was last updated.

Click to expand customer_waiting_since

friendly
STRING

A user-friendly version of the waiting period.

last_reply_from
STRING

Indicates if the last reply was from a user or a customer.

time
DATE-TIME

The UTC time since the last reply sent to the customer.
conversations (table), customer_waiting_since (attribute)

folder_id
INTEGER

The ID of the mailbox folder the conversation is in.

Reference:

mailbox_id
INTEGER

The ID of the mailbox the conversation is in.

Reference:

number
INTEGER

preview
STRING

Preview text from the start of the conversation.

primary_customer
OBJECT

Details about the primary customer in the conversation.

Click to expand primary_customer

email
STRING

The customer’s email address.

first
STRING

The customer’s first name.

id
INTEGER

The customer’s user ID.

Reference:

last
STRING

The customer’s last name.

photo_url
STRING

The URL of the customer’s photo, if one exists.

type
STRING

The user type. Possible values are:

  • team
  • user
conversations (table), primary_customer (attribute)

source
OBJECT

Details about the originating source of the conversation.

Click to expand source

type
STRING

The originating type of the conversation: email, web, API, etc.

via
STRING

The originating source of the conversation. Possible values are:

  • user
  • customer
conversations (table), source (attribute)

state
STRING

The state of the conversation. Possible values are:

  • deleted
  • draft
  • published

status
STRING

The status of the conversation. Possible values are:

  • active
  • all
  • closed
  • open
  • pending
  • spam

subject
STRING

The subject of the conversation.

tags
ARRAY

A list of tags applied to the conversation.

Click to expand tags

value
STRING

The tag applied to the conversation.
conversations (table), tags (attribute)

threads
INTEGER

The number of threads the conversation has.

type
STRING

The type of the conversation. Possible values are:

  • chat
  • email
  • phone

conversation_threads

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

created_at
Primary Key :

id

 API endpoint :

List threads

The conversation_threads table contains info about the threads that make up conversations.

conversation_threads table schema

id
INTEGER

The conversation thread ID.

created_at
DATE-TIME

The UTC time the conversation thread was created.

action
OBJECT

Details about the action taken on the conversation thread.

Click to expand action

text
STRING

Applicable when thread type: lineitem. A user-friendly description of the action.

type
STRING

The type of the action.
conversation_threads (table), action (attribute)

assigned_to
OBJECT

Details about the assignee of the conversation thread.

Click to expand assigned_to

email
STRING

The assignee’s email address.

first
STRING

The assignee’s first name.

id
INTEGER

The assignee’s user ID.

Reference:

last
STRING

The assignee’s last name.

photo_url
STRING

The URL of the assignee’s photo, if one exists.

type
STRING

The user type. Possible values are:

  • team
  • user
conversation_threads (table), assigned_to (attribute)

attachments
ARRAY

A list of conversation attachments.

bcc
ARRAY

A list of emails that have been BCC’d on the conversation.

Click to expand bcc

value
STRING

The email that was BCC’d on the conversation.
conversation_threads (table), bcc (attribute)

body
STRING

The text content of the conversation thread.

cc
ARRAY

A list of emails that have been CC’d on the conversation.

Click to expand cc

value
STRING

The email that was CC’d on the conversation.
conversation_threads (table), cc (attribute)

conversation_id
INTEGER

The ID of the conversation the thread is associated with.

Reference:

created_by
OBJECT

Details about the user that created the conversation thread.

Click to expand created_by

email
STRING

The user’s email address.

first
STRING

The user’s first name.

id
INTEGER

The user’s user ID.

Reference:

last
STRING

The user’s last name.

photo_url
STRING

The URL of the user’s photo, if one exists.

type
STRING

The user type. Possible values are:

  • team
  • user
conversation_threads (table), created_by (attribute)

customer
OBJECT

If type: message, this will contain details about the customer associated with the conversation.

If type: customer, this will contain details about the customer who initiated the thread.

Click to expand customer

email
STRING

The customer’s email address.

first
STRING

The customer’s first name.

id
INTEGER

The customer’s user ID.

Reference:

last
STRING

The customer’s last name.

photo_url
STRING

The URL of the customer’s photo, if one exists.

type
STRING

The user type. Possible values are:

  • team
  • user
conversation_threads (table), customer (attribute)

opened_at
DATE-TIME

Applicable only when type: message. The time the thread was viewed by the customer.

saved_reply_id
INTEGER

The ID of the saved reply used to create the thread.

source
OBJECT

Details about the originating source of the conversation thread.

Click to expand source

type
STRING

The originating type of the conversation thread: email, web, API, etc.

via
STRING

The originating source of the conversation thread. Possible values are:

  • user
  • customer
conversation_threads (table), source (attribute)

state
STRING

The state of the thread. Possible values are:

  • draft
  • hidden
  • published
  • review

status
STRING

The status of the thread. Possible values are:

  • active
  • closed
  • nochange
  • pending
  • spam

to
ARRAY

A list of emails that from the to: field.

Click to expand to

value
STRING

The email included in the to: field.
conversation_threads (table), to (attribute)

type
STRING

The type of the thread. Possible values are:

  • beaconchat
  • chat
  • customer
  • fowardchild
  • forwardparent
  • lineitem
  • message
  • note
  • phone

customers

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

List customers

The customers table contains info about the customers in your Help Scout account.

customers table schema

id
INTEGER

The customer ID.

Reference:

updated_at
DATE-TIME

The UTC time when the customer was last updated.

address
OBJECT

The customer’s physical address.

Click to expand address

city
STRING

The city.

country
STRING

The country.

lines
ARRAY

The street lines of the address.

Click to expand lines

value
STRING

The street line of the address.
customers (table), lines (attribute)

postal_code
STRING

The postal code.

state
STRING

The state.
customers (table), address (attribute)

age
STRING

The customer’s age.

background
STRING

The contents of the Notes field from the user interface in Help Scout.

chats
ARRAY

Details about the customer’s chat handles.

Click to expand chats

id
INTEGER

The chat handle ID.

value
STRING

The chat handle.

type
STRING

The type of the chat handle. For example: icq
customers (table), chats (attribute)

created_at
DATE-TIME

The UTC time when the customer was created.

emails
ARRAY

Details about the customer’s email addresses.

Click to expand emails

id
INTEGER

The email address ID.

value
STRING

The email address.

type
STRING

The type of the email address. For example: work
customers (table), emails (attribute)

first_name
STRING

The first name of the customer.

gender
STRING

The customer’s gender. Possible values are:

  • male
  • female
  • unknown

job_title
STRING

The customer’s job title.

last_name
STRING

The last name of the customer.

location
STRING

The location of the customer.

organization
STRING

The organization the customer is associated with.

phones
ARRAY

Details about the customer’s phone number(s).

Click to expand phones

id
INTEGER

The phone number ID.

value
STRING

The phone number.

type
STRING

The type of phone number. For example: mobile
customers (table), phones (attribute)

photo_type
STRING

The type of photo associated with the customer. Possible values are:

  • unknown
  • gravatar
  • twitter
  • facebook
  • googleprofile
  • googleplus
  • linkedin

photo_url
STRING

The URL of the customer’s photo.

properties
ARRAY

Custom properties setup by customer on their profile.

Click to expand properties

items
OBJECT

Click to expand items

type
STRING

The type of property.

name
STRING

The property name.

value
STRING

The property value.
customers (table), items (attribute)
customers (table), properties (attribute)

social_profiles
ARRAY

Details about the customer’s social profiles.

Click to expand social_profiles

id
INTEGER

The social profile ID.

value
STRING

The URL of the customer’s social profile.

type
STRING

The type of social profile. For example: twitter
customers (table), social_profiles (attribute)

websites
ARRAY

Details about the customer’s websites.

Click to expand websites

id
INTEGER

The website ID.

value
STRING

The URL of the website.
customers (table), websites (attribute)

happiness_ratings_report

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

conversation_id : rating_created_at : rating_customer_id
API endpoint :

Happiness ratings report

The happiness ratings report provides a company’s ratings for a specified time range.

happiness_ratings_report table schema

conversation_id
INTEGER

Conversation ID

rating_comments
STRING

Rating Comments from customer

rating_created_at
DATE-TIME

Date of creation of rating

rating_customer_id
INTEGER

ID of the custimer who gave the rating

rating_customer_name
STRING

Name of the custimer who gave the rating

rating_id
INTEGER

Rating ID. Possible values are 1,2,3 1: Great, 2: Ok, 3: Not Good

rating_user_id
INTEGER

ID of the user who got the rating

rating_user_name
STRING

Name of the user who got the rating

thread_created_at
DATE-TIME

Date of creation of conversation thread

thread_id
INTEGER

Converstaion thread ID

type
STRING

Rating given via. Example: email, chat etc..

mailboxes

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

List mailboxes

The mailboxes table contains info about the mailboxes in your Help Scout account.

mailboxes table schema

id
INTEGER

The mailbox ID.

Reference:

updated_at
DATE-TIME

The UTC time the mailbox was last updated.

created_at
DATE-TIME

The UTC time the mailbox was created.

email
STRING

The email address for the mailbox.

name
STRING

The name of the mailbox.

slug
STRING

The key used to represent the mailbox.

mailbox_fields

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

id
API endpoint :

List mailbox custom fields

The mailbox_fields table contains info about the custom fields associated with your Help Scout mailboxes.

mailbox_fields table schema

id
INTEGER

The mailbox field ID.

mailbox_id
INTEGER

The ID of the mailbox associated with the mailbox field.

Reference:

name
STRING

The name of the mailbox field.

options
ARRAY

Applicable when type: dropdown. The options for the dropdown field.

Click to expand options

id
INTEGER

The option ID.

order
INTEGER

The order the option is displayed in in Help Scout.

label
STRING

The option label.
mailbox_fields (table), options (attribute)

order
INTEGER

The order the mailbox field is displayed in in Help Scout.

required
BOOLEAN

Indicates if the mailbox field is required.

type
STRING

The type of the mailbox field.

mailbox_folders

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

List mailbox folders

The mailbox_folders table contains info about the mailbox folders in your Help Scout account.

mailbox_folders table schema

id
INTEGER

The mailbox folder ID.

Reference:

updated_at
DATE-TIME

The UTC time when the mailbox folder was last updated.

active_count
INTEGER

The number of active conversations in the mailbox folder.

mailbox_id
INTEGER

The ID of the mailbox containing the folder.

Reference:

name
STRING

The name of the mailbox folder.

total_count
INTEGER

The total number of conversations in the mailbox folder.

type
STRING

The type of the mailbox folder.

user_id
INTEGER

teams

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

List teams

This report contains information about all the different teams in the company.

teams table schema

created_at
DATE-TIME

Creation date

id
INTEGER

Team ID

initials
STRING

Team initials

mention
STRING

Details about the team

name
STRING

Team name

photo_url
STRING

Photo URL of the team’s logo

timezone
STRING

Timezone of the team

updated_at
DATE-TIME

Date of last update

team_members

View table schema on GitHub
Replication Method :

Full Table

 Primary Key :

team_id : user_id
API endpoint :

List team members

This report contains information about team members.

team_members table schema

team_id
INTEGER

ID of the team

user_id
INTEGER

ID of the User

users

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

updated_at
Primary Key :

id

 API endpoint :

List users

The users table contains info about the users in your Help Scout account.

users table schema

id
INTEGER

The user ID.

Reference:

updated_at
DATE-TIME

The UTC time the user was last updated.

created_at
DATE-TIME

The UTC time the user was created.

email
STRING

The user’s email address.

first_name
STRING

The user’s first name.

last_name
STRING

The user’s last name.

photo_url
STRING

The URL of the user’s photo.

role
STRING

The role of the user. Possible values are:

  • owner
  • admin
  • user

timezone
STRING

The user’s timezone.

type
STRING

The type of the user. Possible values are:

  • user
  • team

workflows

View table schema on GitHub
Replication Method :

Key-based Incremental

 Replication Key :

modified_at
Primary Key :

id

 API endpoint :

List workflows

The workflows table contains info about the workflows in your Help Scout account.

workflows table schema

id
INTEGER

The workflow ID.

modified_at
DATE-TIME

The UTC time the workflow was last modified.

created_at
DATE-TIME

The UTC time the workflow was created.

mailbox_id
INTEGER

The ID of the mailbox the workflow is associated with.

Reference:

name
STRING

The name of the workflow.

order
INTEGER

The order of the workflow.

status
STRING

The current status of the workflow. Possible values are:

  • active
  • inactive
  • invalid

type
STRING

The type of the workflow.
Related Troubleshooting
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.