This integration is powered by Singer's Freshdesk tap. For support, visit the GitHub repo or join the Singer Slack.
Freshdesk integration summary
Stitch’s Freshdesk integration replicates data using the Freshdesk REST API. Refer to the Schema section for a list of objects available for replication.
Freshdesk feature snapshot
A high-level look at Stitch's Freshdesk (v1) integration, including release status, useful links, and the features supported in Stitch.
STITCH | |||
Release status |
Released on March 1, 2017 |
Supported by | |
Stitch plan |
Standard |
API availability |
Available |
Singer GitHub repository | |||
REPLICATION SETTINGS | |||
Anchor Scheduling |
Supported |
Advanced Scheduling |
Supported |
Table-level reset |
Unsupported |
Configurable Replication Methods |
Unsupported |
DATA SELECTION | |||
Table selection |
Unsupported |
Column selection |
Unsupported |
Select all |
Unsupported |
||
TRANSPARENCY | |||
Extraction Logs |
Supported |
Loading Reports |
Supported |
Connecting Freshdesk
Freshdesk setup requirements
To set up Freshdesk in Stitch, you need:
-
Administrator permissions in Freshdesk. As Stitch will only be able to replicate data that the authorizing user access to, we recommend that someone with these permissions complete the setup. For example: if the authorizing user only has access to a handful of tickets, Stitch will only be able to access and replicate the data for those tickets.
Having a Freshdesk administrator create the integration will ensure that Stitch is able to replicate all the data in your Freshdesk account.
Step 1: Retrieve your Freshdesk API Key
- Sign into your Freshdesk account.
- Click the user menu (your icon) > Profile Settings.
- Your API Key will display under the Change Password section of your profile page.
Leave this page open for now - you’ll need it to wrap things up in Stitch.
Step 2: Add Freshdesk as a Stitch data source
- Sign into your Stitch account.
-
On the Stitch Dashboard page, click the Add Integration button.
-
Click the Freshdesk icon.
-
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 Freshdesk” would create a schema called
stitch_freshdesk
in the destination. Note: Schema names cannot be changed after you save the integration.
Step 3: Define the historical replication start date
The Sync Historical Data setting defines the starting date for your Freshdesk integration. This means that data equal to or newer than this date will be replicated to your data warehouse.
Change this setting if you want to replicate data beyond Freshdesk’s default setting of 1 year. For a detailed look at historical replication jobs, check out the Syncing Historical SaaS Data guide.
Step 4: 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.
Freshdesk integrations support the following replication scheduling methods:
-
Advanced Scheduling using Cron (Advanced or Premium plans only)
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.
Initial and historical replication jobs
After you finish setting up Freshdesk, 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.
Initial replication jobs with Anchor Scheduling
If using Anchor Scheduling, an initial replication job may not kick off immediately. This depends on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.
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.
Freshdesk table reference
Schemas and versioning
Schemas and naming conventions can change from version to version, so we recommend verifying your integration’s version before continuing.
The schema and info displayed below is for version 1 of this integration.
This is the latest version of the Freshdesk integration.
Table and column names in your destination
Depending on your destination, table and column names may not appear as they are outlined below.
For example: Object names are lowercased in Redshift (CusTomERs
> customers
), while case is maintained in PostgreSQL destinations (CusTomERs
> CusTomERs
). Refer to the Loading Guide for your destination for more info.
agents
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The agents
table contains info about the agents in your Freshdesk account.
id
The agent ID. Reference: |
|||||||||||
updated_at
The last time the agent was updated. |
|||||||||||
available
Indicates if the agent is taking new tickets. |
|||||||||||
available_since
Dependent on the value of the |
|||||||||||
occasional
Indicates if the agent is an occasional agent. |
|||||||||||
signature
The HTML-formatted signature of the agent. |
|||||||||||
ticket_scope
The ticket permission of the agent. Possible values include:
|
|||||||||||
group_ids
The group IDs associated with the agent.
|
|||||||||||
role_ids
The role IDs associated with the agent.
|
|||||||||||
created_at
The timestamp when the agent was created. |
|||||||||||
contact
Details about the contact info associated with the agent.
|
companies
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The companies
table contains info about the companies your various customers and contacts belong to.
Custom Fields
If applicable, Stitch will replicate custom fields related to companies
in Freshdesk.
id
The company ID. Reference: |
|
updated_at
The last time the company was updated. |
|
description
The description of the company. |
|
domains
The domains (ex:
|
|
name
The name of the company. |
|
note
Any notes about the company. |
|
created_at
The timestamp when the company was first created. |
conversations
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The conversations
table contains info about replies and public/private notes added to the tickets in your Freshdesk account.
id
The conversation ID. |
|
updated_at
The last time the conversation was updated. |
|
body_text
The content of the conversation in plain text. |
|
incoming
Indicates if the conversation should appear as being created from ‘outside’, ie: not through the Freshdesk web portal. |
|
private
Indicates if a note is private. |
|
user_id
The ID of the agent/user who added the conversation. |
|
support_email
The email address from which replies are sent. For notes, this will be |
|
source
Denotes the type of conversation. |
|
ticket_id
The ID of the ticket to which the conversation is being added. Reference: |
|
to_emails
Email addresses of agents/users who should be notified about the conversation.
|
|
from_email
The email address that the message was sent from. |
|
cc_emails
Email addresses of agents/users who should be CC’d on the conversation.
|
|
bcc_emails
Email addresses of agents/users who should be BCC’d on the conversation.
|
|
created_at
The timestamp of when the conversation was first created. |
groups
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The groups
table contains info about the groups your agents belong to.
id
The group ID. Reference: |
|
updated_at
The timestamp when the group was last updated. |
|
agent_ids
IDs of the agents that belong to the group.
|
|
auto_ticket_assign
Indicates if automatic ticket assignment is enabled for the group. |
|
business_hour_id
Unique ID of the business hour associated with the group. |
|
description
The description of the group. |
|
escalate_to
The ID of the user to whom an escalation email is sent if a ticket is unassigned. |
|
name
The name of the group. |
|
unassigned_for
The time after which an escalation email is sent if a ticket remains unassigned. Possible values include:
|
|
created_at
The timestamp when the group was first created. |
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The roles
table contains info about the various roles that can be assigned to team members in your Freshdesk account.
id
The role ID. Reference: |
updated_at
The timestamp when the role was last updated. |
description
The description of the role. |
name
The name of the role. |
default
Indicates if the role is the default. |
created_at
The timestamp when the role was first created. |
satisfaction_ratings
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The satisfaction_ratings
table contains info about customer satisfaction survey responses, or satisfaction ratings.
id
The ID of the satisfaction rating. Reference: |
||
updated_at
The time when the satisfaction rating was last updated. |
||
user_id
The requester ID of the ticket for which the satisfaction rating has been created or the ID of the user who created the satisfaction rating. |
||
feedback
Feedback given alongisde the satisfaction rating. |
||
created_at
The time the satisfaction rating was first created. |
||
agent_id
The responder ID of the ticket for which the satisfaction rating has been created. Reference: |
||
group_id
The group ID associated with the ticket for which the satisfaction rating has been created. Reference: |
||
ticket_id
The ID of the ticket for which the satisfaction rating has been created. Reference: |
||
survey_id
The survey ID of the satisfaction rating. |
||
ratings
Details about the questions and responses given by the user for the survey.
|
tickets
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The tickets
table contains info about the tickets in your Freshdesk account.
Custom Fields
If applicable, Stitch will replicate custom fields related to tickets
in Freshdesk.
id
The ticket ID. Reference: |
|
updated_at
The time the ticket was most recently updated. |
|
cc_emails
The email addresses added in the
|
|
type
The category/type of ticket. |
|
to_emails
Email addresses to which the ticket was originally sent.
|
|
fwd_emails
Email addresses added while forwarding a ticket.
|
|
source
The channel through which the ticket was created. |
|
due_by
Denotes the due time of the ticket. |
|
company_id
The ID of the company to which the ticket belongs. Reference: |
|
responder_id
The ID of the agent assigned to the ticket. Reference: |
|
priority
The priority of the ticket. |
|
deleted
Indicates if the ticket has been deleted/trashed. |
|
facebook_id
The Facebook ID of the requester. |
|
subject
The subject of the ticket. |
|
fr_due_by
The time when the first response is due. |
|
email
The email address of the requester. |
|
status
The status of the ticket. |
|
is_escalated
Indicates if the ticket has been escalated for any reason. |
|
reply_cc_emails
Email addresses added while responding to the ticket.
|
|
description
The HTML content of the ticket. |
|
tags
The tags associated with the ticket.
tickets (table), tags (attribute)
|
|
email_config_id
The ID of the email config used for the ticket. Ex: |
|
phone
The phone number associated with the requester. |
|
description_text
The content of the ticket in plain text. |
|
requester_id
The ID of the requester. |
|
name
The name of the requester. |
|
product_id
The ID of the product associated with the ticket. |
|
fr_escalated
Indicates if the ticket has been escalated as a result of the first response time being breached. |
|
created_at
The time the ticket was created. |
|
spam
Indicates if the ticket has been marked as spam. |
|
twitter_id
The Twitter handle of the requester. |
|
group_id
The ID of the group to which the ticket has been assigned. Reference: |
time_entries
Replication Method : |
Key-based Incremental |
Replication Key |
updated_at |
Primary Key |
id |
API endpoint : |
The time_entries
table contains info about the time entries entered by agents working on tickets.
id
The ID of the time entry record. |
updated_at
The time the time entry record was last updated. |
time_spent
The duration of the time entry record in |
start_time
The time at which the time entry record is added or the time of the last invoked ‘start-timer’ action using a toggle. |
created_at
The time the time entry record was created. |
executed_at
The time the time entry record was added/created. |
timer_running
Indicates if the time is currently running. |
note
The description of the time entry. |
ticket_id
The ID of the ticket associated with the time entry record. Reference: |
billable
Indicates if the time entry record is billable. |
agent_id
The agent ID associated with the time entry. Reference: |
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.