# Freshservice

Freshservice is a cloud-based IT service management (ITSM) platform by Freshworks. The Sling Freshservice connector extracts data from the Freshservice REST API v2, supporting tickets, agents, requesters, assets, changes, problems, releases, departments, groups, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `api_key` **(required)** -> Your Freshservice API key
* `domain` **(required)** -> Your Freshservice domain (e.g., `yourcompany.freshservice.com`)

**Inputs:**

* `anchor_date` (optional) -> Starting date for first sync of incremental endpoints (ISO 8601 format, e.g., `2024-01-01T00:00:00Z`). Defaults to 1 year ago.

### Authentication

Freshservice uses HTTP Basic Authentication with your API key:

1. Log in to your Freshservice account at `https://yourcompany.freshservice.com`
2. Click your **profile icon** (top right) and select **Profile Settings**
3. Your API key is displayed under **Your API Key**
4. If the API key is disabled, ask your account admin to enable it:
   * Go to **Admin > Agents** and click on the agent
   * Click the **Permissions** tab
   * Toggle the **API key** switch to enable it

{% hint style="info" %}
**Note:** The API key is used as the username in Basic Auth with `X` as the password. All requests are made over HTTPS.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set FRESHSERVICE type=api spec=freshservice secrets='{ api_key: your_api_key, domain: yourcompany.freshservice.com }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export FRESHSERVICE='{ type: api, spec: freshservice, secrets: { api_key: "your_api_key", domain: "yourcompany.freshservice.com" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  FRESHSERVICE:
    type: api
    spec: freshservice
    secrets:
      api_key: "your_api_key"
      domain: "yourcompany.freshservice.com"
```

## Replication

Here's an example replication configuration to sync Freshservice data to a PostgreSQL database:

```yaml
source: FRESHSERVICE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: freshservice.{stream_name}

streams:
  # sync all endpoints
  '*':
```

**Incremental sync for supported endpoints:**

```yaml
source: FRESHSERVICE
target: MY_POSTGRES

defaults:
  object: freshservice.{stream_name}

streams:
  tickets:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  releases:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  changes:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  problems:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  # Full-refresh only endpoints
  agents:
    mode: full-refresh
  requesters:
    mode: full-refresh
  departments:
    mode: full-refresh
  groups:
    mode: full-refresh
  assets:
    mode: full-refresh
  locations:
    mode: full-refresh
  products:
    mode: full-refresh
  vendors:
    mode: full-refresh
  software:
    mode: full-refresh
  purchase_orders:
    mode: full-refresh
  contracts:
    mode: full-refresh
  roles:
    mode: full-refresh
  asset_types:
    mode: full-refresh
  satisfaction_survey_responses:
    mode: full-refresh
```

## Endpoints

| Endpoint                        | Description                | Incremental |
| ------------------------------- | -------------------------- | ----------- |
| `tickets`                       | All tickets with stats     | Yes         |
| `releases`                      | All releases               | Yes         |
| `changes`                       | All changes                | Yes         |
| `problems`                      | All problems               | Yes         |
| `agents`                        | All agents                 | No          |
| `requesters`                    | All requesters             | No          |
| `departments`                   | All departments            | No          |
| `groups`                        | All agent groups           | No          |
| `assets`                        | All assets                 | No          |
| `locations`                     | All locations              | No          |
| `products`                      | All products               | No          |
| `vendors`                       | All vendors                | No          |
| `software`                      | All software applications  | No          |
| `purchase_orders`               | All purchase orders        | No          |
| `contracts`                     | All contracts              | No          |
| `roles`                         | All roles                  | No          |
| `asset_types`                   | All asset types            | No          |
| `satisfaction_survey_responses` | CSAT responses for tickets | No          |

To discover available endpoints:

```bash
sling conns discover FRESHSERVICE
```

## Incremental Sync

The `tickets`, `releases`, `changes`, and `problems` endpoints support incremental sync using the `updated_since` parameter:

* **First run:** Fetches all records updated within the last year (or since `anchor_date` if provided)
* **Subsequent runs:** Only fetches records modified after the last sync timestamp
* **Update key:** `updated_at` for all incremental endpoints

All other endpoints run in full-refresh mode since they do not support time-based filtering.

## Rate Limiting

The Freshservice API enforces per-plan rate limits (100-500 requests/minute depending on your subscription). The connector automatically:

* Uses conservative rate limiting (1 request/second)
* Retries with exponential backoff on 429 (rate limit) responses, up to 5 attempts

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).