Release Status Released Supported By Singer community
Availability Free Status Page Freshdesk Status Page
Default Historical Sync 1 year Default Replication Frequency 30 minutes
Whitelisting Unsupported Destination Incompatibilities None

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

  1. Sign into your Freshdesk account.
  2. Click the user menu (your icon) > Profile Settings.
  3. 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

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

  3. Click the Freshdesk icon.

  4. Enter a name for the integration. This is the name that will display on the 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 Sync

The Sync Historical Data setting will define 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 sync data beyond Freshdesk’s default setting of 1 year. For a detailed look at historical syncs, 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.

Stitch offers two methods of creating a replication schedule:

  • Replication Frequency: This method requires selecting the interval you want replication to run for the integration. Start times of replication jobs are based on the start time and duration of the previous job. Refer to the Replication Frequency documentation for more information and examples.
  • Anchor scheduling: Based on the Replication Frequency, or interval, you select, this method “anchors” the start times of this integration’s replication jobs to a time you select to create a predictable schedule. Anchor scheduling is a combination of the Anchor Time and Replication Frequency settings, which must both be defined to use this method. Additionally, note that:

    • A Replication Frequency of at least one hour is required to use anchor scheduling.
    • An initial replication job may not begin immediately after saving the integration, depending on the selected Replication Frequency and Anchor Time. Refer to the Anchor Scheduling documentation for more information.

To help prevent overages, 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.

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 Schemas

Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: listAllAgents

The agents table contains info about the agents in your Freshdesk account.

id
INTEGER

The agent ID.

updated_at
DATE-TIME

The last time the agent was updated.

available
BOOLEAN

Indicates if the agent is taking new tickets.

available_since
DATE-TIME

Dependent on the value of the available attribute, this timestamp denotes when the agent became available/unavailable.

occasional
BOOLEAN

Indicates if the agent is an occasional agent.

signature
STRING

The HTML-formatted signature of the agent.

ticket_scope
INTEGER

The ticket permission of the agent. Possible values include:

  • 1 - Global Access
  • 2 - Group Access
  • 3 - Restricted Access
group_ids

The group IDs associated with the agent.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named agents__group_ids and may contain the following attributes:

_sdc_source_key_id
INTEGER

The agent ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

type
INTEGER

The ID of the group.

role_ids

The role IDs associated with the agent.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named agents__role_ids and may contain the following attributes:

_sdc_source_key_id
INTEGER

The agent ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

type
INTEGER

The ID of the role.

created_at
DATE-TIME

The timestamp when the agent was created.

contact__active
BOOLEAN

Indicates if the agent is verified.

contact__email
STRING

The email address associated with the agent.

contact__job_title
STRING

The job title of the agent.

contact__language
STRING

The language of the agent. en is the default.

contact__last_login_at
DATE-TIME

The timestamp when the agent last logged in.

contact__mobile
STRING

The mobile number of the agent.

contact__name
STRING

The agent’s name.

contact__phone
STRING

The phone number of the agent.

contact__time_zone
STRING

The timezone of the agent.

contact__created_at
DATE-TIME

The timestamp when the agent’s contact details were first created.

contact__updated_at
DATE-TIME

The timestamp of the last time the agent’s contact details were updated.


companies

Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: listAllCompanies

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
INTEGER

The company ID.

updated_at
DATE-TIME

The last time the company was updated.

description
STRING

The description of the company.

domains

The domains (ex: stitchdata.com) associated with the company.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named companies__domains and may contain the following attributes:

_sdc_source_key_id
INTEGER

The company ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The domain (ex: stitchdata.com) associated with the company.

name
STRING

The name of the company.

note
STRING

Any notes about the company.

created_at
DATE-TIME

The timestamp when the company was first created.


Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: listAllConversationsOfATicket

The conversations table contains info about replies and public/private notes added to the tickets in your Freshdesk account.”

id
INTEGER

The conversation ID.

updated_at
DATE-TIME

The last time the conversation was updated.

body_text
STRING

The content of the conversation in plain text.

incoming
BOOLEAN

Indicates if the conversation should appear as being created from ‘outside’, ie: not through the Freshdesk web portal.

private
BOOLEAN

Indicates if a note is private.

user_id
INTEGER

The ID of the agent/user who added the conversation.

support_email
STRING

The email address from which replies are sent. For notes, this will be NULL.

source
INTEGER

Denotes the type of conversation.

ticket_id
INTEGER

The ID of the ticket to which the conversation is being added.

to_emails

Email addresses of agents/users who should be notified about the conversation.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named conversations__to_emails and may contain the following attributes:

_sdc_source_key_id
INTEGER

The conversation ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The email address of the person who should be notified about the conversation.

from_email
STRING

The email address that the message was sent from.

cc_emails

Email addresses of agents/users who should be CC’d on the conversation.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named conversations__cc_emails and may contain the following attributes:

_sdc_source_key_id
INTEGER

The conversation ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The email address of the person who is being CC’d.

bcc_emails

Email addresses of agents/users who should be BCC’d on the conversation.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named conversations__bcc_emails and may contain the following attributes:

_sdc_source_key_id
INTEGER

The conversation ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The email address of the person who is being BCC’d.

created_at
DATE-TIME

The timestamp of when the conversation was first created.


Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: listAllGroups

The groups table contains info about the groups your agents belong to.

id
INTEGER

The group ID.

updated_at
DATE-TIME

The timestamp when the group was last updated.

agent_ids

IDs of the agents that belong to the group.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named groups__agent_ids and may contain the following attributes:

_sdc_source_key_id
INTEGER

The group ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
INTEGER

The ID of an agent that belongs to the group.

auto_ticket_assign
BOOLEAN

Indicates if automatic ticket assignment is enabled for the group.

business_hour_id
INTEGER

Unique ID of the business hour associated with the group.

description
STRING

The description of the group.

escalate_to
INTEGER

The ID of the user to whom an escalation email is sent if a ticket is unassigned.

name
STRING

The name of the group.

unassigned_for
STRING

The time after which an escalation email is sent if a ticket remains unassigned. Possible values include:

  • 30m for 30 minutes
  • 1h for 1 hour
  • 2h for 2 hours
  • 4h for 4 hours
  • 8h for 8 hours
  • 12h for 12 hours
  • 1d for 1 day
  • 2d for 2 days
  • 3d for 3 days
created_at
DATE-TIME

The timestamp when the group was first created.


Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: listAllRoles

The roles table contains info about the various roles that can be assigned to team members in your Freshdesk account.

id
INTEGER

The role ID.

updated_at
DATE-TIME

The timestamp when the role was last updated.

description
STRING

The description of the role.

name
STRING

The name of the role.

default
BOOLEAN

Indicates if the role is the default.

created_at
DATE-TIME

The timestamp when the role was first created.


satisfaction_ratings

Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: viewAllSatisfactionRatings

The satisfaction-ratings table contains info about customer satisfaction survey responses, or satisfaction ratings.”

id
INTEGER

The ID of the satisfaction rating.

updated_at
DATE-TIME

The time when the satisfaction rating was last updated.

user_id
INTEGER

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
STRING

Feedback given alongisde the satisfaction rating.

created_at
DATE-TIME

The time the satisfaction rating was first created.

agent_id
INTEGER

The responder ID of the ticket for which the satisfaction rating has been created.

group_id
INTEGER

The group ID associated with the ticket for which the satisfaction rating has been created.

ticket_id
INTEGER

The ID of the ticket for which the satisfaction rating has been created.

survey_id
INTEGER

The survey ID of the satisfaction rating.

ratings

Details about the questions and responses given by the user for the survey.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named satisfaction_ratings__ratings and may contain the following attributes:

_sdc_source_key_id
INTEGER

The ID of the satisfaction rating.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

question
STRING

The question associated with the survey.

value
INTEGER

The value of the user’s response to the survey question.


Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: listAllTickets

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
INTEGER

The ticket ID.

updated_at
DATE-TIME

The time the ticket was most recently updated.

cc_emails

The email addresses added in the cc field of the ticket.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named tickets__cc_emails and may contain the following attributes:

_sdc_source_key_id
INTEGER

The ticket ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The email address added in the cc field of the ticket.

type
STRING

The category/type of ticket.

to_emails

Email addresses to which the ticket was originally sent.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named tickets__to_emails and may contain the following attributes:

_sdc_source_key_id
INTEGER

The ticket ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The email address to which the ticket was originally sent.

fwd_emails

Email addresses added while forwarding a ticket.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named tickets__fwd_emails and may contain the following attributes:

_sdc_source_key_id
INTEGER

The ticket ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The email address that was added while forwarding a ticket.

source
NUMBER

The channel through which the ticket was created.

due_by
DATE-TIME

Denotes the due time of the ticket.

company_id
INTEGER

The ID of the company to which the ticket belongs.

responder_id
INTEGER

The ID of the agent assigned to the ticket.

priority
NUMBER

The priority of the ticket.

deleted
BOOLEAN

Indicates if the ticket has been deleted/trashed.

facebook_id
STRING

The Facebook ID of the requester.

subject
STRING

The subject of the ticket.

fr_due_by
DATE-TIME

The time when the first response is due.

email
STRING

The email address of the requester.

status
NUMBER

The status of the ticket.

is_escalated
BOOLEAN

Indicates if the ticket has been escalated for any reason.

reply_cc_emails

Email addresses added while responding to the ticket.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named tickets__reply_cc_emails and may contain the following attributes:

_sdc_source_key_id
INTEGER

The ticket ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The email address added while responding to the ticket.

description
STRING

The HTML content of the ticket.

tags

The tags associated with the ticket.

This data may be de-nested into a subtable if your data warehouse doesn't natively support nested data.

This subtable would be named tickets__tags and may contain the following attributes:

_sdc_source_key_id
INTEGER

The ticket ID.

_sdc_level_0_id
INTEGER

This column forms part of a composite key for the table. The value will auto-increment for each unique record, beginning with 0.

value
STRING

The tag associated with the ticket.

email_config_id
INTEGER

The ID of the email config used for the ticket. Ex: support@stitchdata.com

phone
STRING

The phone number associated with the requester.

description_text
STRING

The content of the ticket in plain text.

requester_id
INTEGER

The ID of the requester.

name
STRING

The name of the requester.

product_id
INTEGER

The ID of the product associated with the ticket.

fr_escalated
BOOLEAN

Indicates if the ticket has been escalated as a result of the first response time being breached.

created_at
DATE-TIME

The time the ticket was created.

spam
BOOLEAN

Indicates if the ticket has been marked as spam.

twitter_id
STRING

The Twitter handle of the requester.

group_id
INTEGER

The ID of the group to which the ticket has been assigned.


Replication Method: Key-based Incremental Replication Key : updated_at
Primary Key : id API Endpoint: listAllTimeEntries

The time_entries table contains info about the time entries entered by agents working on tickets.

id
INTEGER

The ID of the time entry record.

updated_at
DATE-TIME

The time the time entry record was last updated.

time_spent
STRING

The duration of the time entry record in hh:mm format.

start_time
DATE-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
DATE-TIME

The time the time entry record was created.

executed_at
DATE-TIME

The time the time entry record was added/created.

timer_running
BOOLEAN

Indicates if the time is currently running.

note
STRING

The description of the time entry.

ticket_id
INTEGER

The ID of the ticket associated with the time entry record.

billable
BOOLEAN

Indicates if the time entry record is billable.

agent_id
INTEGER

The agent ID associated with the time entry.



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.