# Freshdesk

> Source: https://docs.clonepartner.com/connectors/freshdesk/

<!-- sources: src/connectors/freshdesk.ts, references/envoy/connectors.md -->

# Freshdesk

The `freshdesk` connector calls the Freshdesk REST v2 API with Basic auth, automatic `Link`-header pagination, rate limiting, retries, and multipart attachment upload.

## When to use it

Use `freshdesk` to export tickets, contacts, and conversations from a Freshdesk account, or to create and update records — including attachment uploads — during a migration. Methods take raw API paths, so any REST v2 endpoint is reachable.

## Configuration

| Key | Type | Required | Default | Description |
|---|---|---|---|---|
| `domain` | string | Yes | — | Freshdesk domain (`acme`, `acme.freshdesk.com`, or a full `https` URL) |
| `api_key` | string | Yes | — | Freshdesk API key (stored as a secret) |
| `rate_limit` | number | No | 10 | Max requests per second |

A bare `domain` value like `acme` resolves to `https://acme.freshdesk.com`. Authentication is HTTP Basic with the API key as username and `X` as password.

## Methods

| Method | Arguments | Returns | Behavior |
|---|---|---|---|
| `find` | `resource` (required), `query`, `items_key`, `page_size` | array | Streams records page by page, following the `Link` response header to the end; `page_size` defaults to 100 (sent as `per_page`) |
| `find_one` | `resource` (required), `id` (required), `query` | object | Fetches a single record by ID |
| `create` | `resource` (required), `data` (required) | object | Creates a record (POST) |
| `update` | `resource` (required), `id` (required), `data` (required) | object | Updates a record by ID (PUT) |
| `delete` | `resource` (required), `id` (required), `ignore_not_found` | void | Deletes a record; with `ignore_not_found: true`, HTTP 404 returns a `not_found` result instead of throwing |
| `execute` | `path` (required), `method` (required), `data`, `query`, `headers` | object | Raw HTTP request for endpoints not covered by the helpers |
| `upload` | `resource` (required), `method`, `fields`, `attachments` | object | Creates or updates a resource with file attachments via `multipart/form-data` (`attachments[]`); each attachment is `{ filename, content_type, base64 }`, total 20 MB per request |

For search/filter endpoints that wrap results in an object, set `items_key` (for example `results` for `api/v2/search/tickets`).

## Example

```yaml
name: export_tickets
connectors:
  source:
    type: freshdesk
steps:
  - name: read_tickets
    type: call_method
    config: |
      {
        "connector": "source",
        "method": "find",
        "args": { "resource": "api/v2/tickets", "query": { "updated_since": "2026-01-01" } }
      }
```

The matching `connectors.yaml` entry for CLI runs:

```yaml
source:
  type: freshdesk
  config:
    domain: acme
    api_key: ${FRESHDESK_API_KEY}
```

## Behavior notes

- Requests are throttled to `rate_limit` per second with a token bucket. `429` responses honor the `Retry-After` header and `5xx` responses use exponential backoff, up to 5 retries; network errors also retry.
- `find` yields each record as it is parsed, so downstream steps process large exports with backpressure.
- `upload` targets the endpoints that accept attachments — ticket create/update and ticket notes/replies. Use `method: PUT` to update a ticket with new attachments.

## Related

- [Connectors overview](/connectors/) — all compiled connector types
- [Jira](/connectors/jira/) — a similar REST connector with the same method shape
- [Reading and writing data](/building/reading-and-writing-data/) — calling connector methods from steps