> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Freshdesk as a data source
> Bring data from Freshdesk to Nekt.
Freshdesk is a cloud-based customer support platform from Freshworks. It lets teams manage tickets across email, chat, phone, and social channels, track SLAs, and coordinate work between agents and groups. This connector extracts your Freshdesk help desk data so you can analyze ticket volume, agent performance, response times, and customer relationships.
## Configuring Freshdesk as a Source
In the [Sources](https://app.nekt.ai/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
Sign in to your Freshdesk account at `https://{your-domain}.freshdesk.com`.
Click your profile picture in the top-right corner and select **Profile settings**.
On the right side of the profile page, click **View API Key** and copy the value.
Store your API key securely. Treat it like a password and do not share it publicly.
#### Configuration Fields
The following configurations are available:
* **Freshdesk domain**: Your Freshdesk subdomain. For an account hosted at `https://acme.freshdesk.com`, this value is `acme`.
* **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`, and `companies` streams.
Once you're done, click **Next**.
### 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.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), 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](https://docs.nekt.com/get-started/core-concepts/types-of-sync#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](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from Freshdesk and their corresponding fields:
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 |
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 |
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` | String | Secondary companies linked to this contact (JSON) |
| `custom_fields` | String | Account-specific custom fields (JSON) |
| `created_at` | DateTime | Creation timestamp |
| `updated_at` | DateTime | Last update timestamp |
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` | String | Account-specific custom fields (JSON) |
| `created_at` | DateTime | Creation timestamp |
| `updated_at` | DateTime | Last update timestamp |
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` | String | Embedded user/contact record for the agent (JSON) |
| `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.
```mermaid theme={null}
erDiagram
Tickets ||--o{ Conversations : "ticket_id"
Tickets }o--|| Contacts : "requester_id"
Tickets }o--|| Agents : "responder_id"
Tickets }o--o| Companies : "company_id"
Contacts }o--o| Companies : "company_id"
Tickets {
int id PK
int requester_id FK
int responder_id FK
int company_id FK
int status
int priority
datetime created_at
datetime updated_at
}
Conversations {
int id PK
int ticket_id FK
int user_id
boolean private
datetime created_at
}
Contacts {
int id PK
string email
int company_id FK
datetime updated_at
}
Companies {
int id PK
string name
datetime updated_at
}
Agents {
int id PK
string type
boolean deactivated
}
```
## 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 `stats` block 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-After` header.
* **Timestamps**: All timestamps are returned in UTC (ISO 8601).
## Skills for agents
Freshdesk connector documentation as plain markdown, for use in AI agent contexts.