Documentation by ClonePartner

Start typing to search.

Connector Reference

Freshdesk

View Markdown

Configure the freshdesk connector for the REST v2 API, stream paginated results, and upload ticket attachments via multipart.

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

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:

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.