Configuring Freshdesk as a Source
In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Freshdesk option from the list of connectors. Click Next and you’ll be prompted to add your access.1. Add account access
You’ll need your Freshdesk subdomain and API key to authenticate. Freshdesk uses HTTP Basic authentication with the API key as the username.Obtaining Your API Key
Configuration Fields
The following configurations are available:- Freshdesk domain: Your Freshdesk subdomain. For an account hosted at
https://acme.freshdesk.com, this value isacme. - API key: The API key copied from your Freshdesk profile page.
- Start date: The earliest date from which records will be synced. This controls the initial window for the
tickets,contacts, andcompaniesstreams.
2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis.Tip: The stream can be found more easily by typing its name.Select the streams and click Next.
3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table, and the type of sync.- Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
- Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
- Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster.
- Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
- Incremental: every time the extraction happens, we’ll get only the new data, which is good if you want to keep every record ever fetched.
- Full table: every time the extraction happens, we’ll get the current state of the data, which is good if you don’t want to have deleted data in your catalog.
4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. Ticket data typically benefits from hourly or daily refreshes depending on your support volume. Optionally, you can determine when to execute an Additional Full Sync. This complements incremental extractions and ensures your data is fully synchronized every once in a while. Once you are ready, click Next to finalize the setup.5. Check your new source
You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.Streams and Fields
Below you’ll find all available data streams from Freshdesk and their corresponding fields:Tickets
Tickets
Stream containing all support tickets, the central fact table for help desk analytics. Supports incremental sync based on the
updated_at field. The stream automatically includes ticket stats (response and resolution timestamps) via the include=stats parameter for SLA analysis.| Field | Type | Description |
|---|---|---|
id | Integer | Unique ticket ID |
subject | String | Ticket subject |
description_text | String | Plain-text description |
type | String | Ticket type (e.g., Question, Incident, Problem, Feature Request) |
status | Integer | Status code: 2=Open, 3=Pending, 4=Resolved, 5=Closed |
priority | Integer | Priority: 1=Low, 2=Medium, 3=High, 4=Urgent |
source | Integer | Source channel (email, portal, phone, chat, etc.) |
spam | Boolean | Whether the ticket is marked as spam |
requester_id | Integer | Contact who created the ticket |
responder_id | Integer | Agent assigned to the ticket |
company_id | Integer | Associated company |
group_id | Integer | Assigned agent group |
product_id | Integer | Product associated with the ticket |
email_config_id | Integer | Email mailbox used |
fr_escalated | Boolean | Whether first response SLA was breached |
is_escalated | Boolean | Whether resolution SLA was breached |
fr_due_by | DateTime | First response due-by timestamp |
due_by | DateTime | Resolution due-by timestamp |
nr_due_by | DateTime | Next response due-by timestamp |
nr_escalated | Boolean | Whether next response SLA was breached |
tags | Array | Ticket tags |
cc_emails | Array | CC emails on the ticket |
fwd_emails | Array | Forwarded emails |
reply_cc_emails | Array | Reply CC emails |
to_emails | Array | To emails on the ticket |
due_by_in_hours | Number | Due-by in hours |
sentiment_score | Number | Latest sentiment score |
initial_sentiment_score | Number | Initial sentiment score |
custom_fields | Object | Account-specific custom fields |
stats.agent_responded_at | DateTime | Last agent response timestamp |
stats.requester_responded_at | DateTime | Last requester response timestamp |
stats.first_responded_at | DateTime | First agent response timestamp |
stats.status_updated_at | DateTime | Last status change timestamp |
stats.reopened_at | DateTime | Reopen timestamp |
stats.resolved_at | DateTime | Resolution timestamp |
stats.closed_at | DateTime | Closure timestamp |
stats.pending_since | DateTime | Pending-since timestamp |
created_at | DateTime | Creation timestamp |
updated_at | DateTime | Last update timestamp |
Conversations
Conversations
Stream containing ticket replies and private notes, fetched per ticket from the
/tickets/{ticket_id}/conversations endpoint. Use this stream to analyze response times, interaction counts, and the full conversation timeline for each ticket.| Field | Type | Description |
|---|---|---|
id | Integer | Unique conversation ID |
ticket_id | Integer | Parent ticket ID |
user_id | Integer | Author (agent or contact) user ID |
from_email | String | Sender email |
to_emails | Array | To email addresses |
cc_emails | Array | CC email addresses |
bcc_emails | Array | BCC email addresses |
body_text | String | Plain-text message body |
incoming | Boolean | Whether the message is incoming (from customer) |
private | Boolean | Whether this is a private note (agent-only) |
source | Integer | Source channel for the conversation |
support_email | String | Support email address used |
category | Integer | Conversation category |
thread_id | Integer | Thread ID for threaded conversations |
thread_message_id | Integer | Thread message ID |
last_edited_at | DateTime | Last edit timestamp |
last_edited_user_id | Integer | User who last edited |
attachments | Array | Attachment objects (id, name, content_type, size, attachment_url, timestamps) |
created_at | DateTime | Creation timestamp |
updated_at | DateTime | Last update timestamp |
Contacts
Contacts
Stream containing all customers who have submitted tickets or been added to the help desk. Supports incremental sync based on the
updated_at field.| Field | Type | Description |
|---|---|---|
id | Integer | Unique contact ID |
name | String | Contact name |
email | String | Primary email |
phone | String | Phone number |
mobile | String | Mobile number |
job_title | String | Job title |
address | String | Address |
description | String | Contact description |
language | String | Preferred language |
time_zone | String | Time zone |
twitter_id | String | Twitter handle |
facebook_id | String | Facebook ID |
unique_external_id | String | External ID from integrated systems |
active | Boolean | Whether the contact is verified/active |
blocked | Boolean | Whether the contact is blocked |
blocked_at | DateTime | Block timestamp |
deleted | Boolean | Whether the contact is soft-deleted |
company_id | Integer | Primary company association |
view_all_tickets | Boolean | Whether contact sees all company tickets |
tags | Array | Contact tags |
other_emails | Array | Additional emails |
other_phone_numbers | Array | Additional phone numbers |
other_companies | Array | Secondary company associations (company_id, view_all_tickets) |
custom_fields | Object | Account-specific custom fields |
created_at | DateTime | Creation timestamp |
updated_at | DateTime | Last update timestamp |
Companies
Companies
Stream containing organizations that group contacts, commonly used for B2B support. Supports incremental sync based on the
updated_at field.| Field | Type | Description |
|---|---|---|
id | Integer | Unique company ID |
name | String | Company name |
description | String | Company description |
note | String | Internal note |
domains | Array | Email domains associated with the company |
health_score | String | Customer health score |
account_tier | String | Account tier (e.g., Premium, Basic) |
renewal_date | DateTime | Contract renewal date |
industry | String | Industry |
custom_fields | Object | Account-specific custom fields |
created_at | DateTime | Creation timestamp |
updated_at | DateTime | Last update timestamp |
Agents
Agents
Stream containing all support agents with their roles, groups, and skills. Extracted as a full-table sync.
| Field | Type | Description |
|---|---|---|
id | Integer | Unique agent ID |
available | Boolean | Whether the agent is currently available |
available_since | DateTime | Timestamp since current availability state |
occasional | Boolean | Whether the agent is occasional (non-full-time) |
signature | String | HTML signature |
ticket_scope | Integer | 1=Global, 2=Group, 3=Restricted access |
type | String | Agent type (support_agent, field_agent, collaborator) |
focus_mode | Boolean | Whether focus mode is enabled |
deactivated | Boolean | Whether the agent has been deactivated |
last_active_at | DateTime | Last active timestamp |
group_ids | Array | Groups the agent belongs to |
role_ids | Array | Roles assigned to the agent |
skill_ids | Array | Skills assigned to the agent |
contact.active | Boolean | Whether the agent’s user record is active |
contact.email | String | Agent email |
contact.job_title | String | Agent job title |
contact.language | String | Preferred language |
contact.last_login_at | DateTime | Last login timestamp |
contact.mobile | String | Mobile number |
contact.name | String | Agent name |
contact.phone | String | Phone number |
contact.time_zone | String | Time zone |
contact.created_at | DateTime | User record creation timestamp |
contact.updated_at | DateTime | User record last update timestamp |
created_at | DateTime | Agent record creation timestamp |
updated_at | DateTime | Agent record last update timestamp |
Data Model
The following diagram illustrates the relationships between the core data streams in Freshdesk. The arrows indicate the join keys that link the different entities.Implementation Notes
Data Sync Considerations
- Incremental sync: Tickets, contacts, and companies support incremental sync based on
updated_at. Agents and conversations are extracted as full-table syncs. - Ticket stats: The tickets stream automatically requests the
statsblock from the Freshdesk API, giving you response and resolution timestamps without a second API call. - Conversations: Conversations are nested under tickets. Any ticket included in a sync will have its conversations re-fetched, so keep this in mind when tuning the start date for high-volume accounts.
API Limits & Performance
- Page cap: The Freshdesk list endpoints cap at 300 pages of 100 records (30,000 records per filter window). For accounts exceeding this, use a recent start date and increase the sync frequency so each incremental window stays within the cap.
- Rate limits: Freshdesk enforces per-minute rate limits that vary by plan. The connector retries on 429 responses using the
Retry-Afterheader. - Timestamps: All timestamps are returned in UTC (ISO 8601).
Skills for agents
Download Freshdesk skills file
Freshdesk connector documentation as plain markdown, for use in AI agent contexts.