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.0) integration, including release status, useful links, and the features supported in Stitch.

STITCH
Release Status Beta Supported By

Singer Community

Stitch Plan

Free

Singer GitHub Repository

Help Scout Repository

DATA SELECTION
Table Selection

Supported

Column Selection

Supported

REPLICATION SETTINGS
Anchor Scheduling

Supported

Advanced Scheduling

Unsupported

Table-level Reset

Unsupported

Configurable Replication Methods

Unsupported

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 sync

The Sync Historical Data setting will define the starting date for your Help Scout integration. This means that:

  • For tables using Incremental Replication, data equal to or newer than this date will be replicated to your data warehouse.
  • 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 data warehouse.

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

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.

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

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 tables and columns to replicate

To complete the setup, you’ll need to select the tables and columns you want to replicate to your data warehouse.

Check out the Schema section to learn more about the available tables in Help Scout and how they replicate.

  1. In the list of tables that displays - or in the Tables to Replicate tab, if you skipped this step during setup - locate a table you want to replicate.
  2. To track a table, click the checkbox next to the table’s name. A green checkmark means the table is set to replicate.

  3. To track a column, click the checkbox next to the column’s name. A green 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.

Note: If you change these settings while a replication job is still in progress, they will not be used until the next job starts.

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 schemas

conversation_threads

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Replication Method :

Key-based Incremental

Replication Key :

user_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.

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.

assignee
OBJECT

Details about the assignee of the conversation.

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.

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.

value
STRING

The email that was CC’d on the conversation.

conversations (table), cc (attribute)

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.

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.

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.

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.

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.

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.

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

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.

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.

city
STRING

The city.

country
STRING

The country.

lines
ARRAY

The street lines of the address.

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.

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.

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).

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.

social_profiles
ARRAY

Details about the customer’s 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.

id
INTEGER

The website ID.

value
STRING

The URL of the website.

customers (table), websites (attribute)

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.

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.

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.


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.

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


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.

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.


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.

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

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.

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.



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.