# Gorgias

Gorgias is a helpdesk platform designed for ecommerce businesses, providing customer support ticketing, automation, and multi-channel communication. The Sling Gorgias connector extracts data from the Gorgias REST API, supporting tickets, customers, messages, tags, and configuration data.

{% 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:**

* `subdomain` **(required)** -> Your Gorgias subdomain (the first part of your Gorgias URL, e.g., `mycompany` from `mycompany.gorgias.com`)
* `email` **(required)** -> Your Gorgias account email address
* `api_key` **(required)** -> Your Gorgias REST API key

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction on first sync (default: 1 year ago). Format: `YYYY-MM-DD`

### Getting Your Credentials

1. Log in to your [Gorgias account](https://app.gorgias.com)
2. Go to **Settings** > **Advanced** > **REST API**
3. Your **Base API URL** and **Username (email)** are displayed
4. Click **Create API key** to generate a new API key
5. Copy the **API key** (Password field) — you can reveal it by clicking the eye icon

{% hint style="warning" %}
**Important:** Store your API key securely. It provides full access to your Gorgias account data. Never commit keys to version control.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set GORGIAS type=api spec=gorgias secrets='{ subdomain: mycompany, email: user@example.com, api_key: xxxxxxxxxxxxxxxx }'
```

{% endcode %}

### Environment Variable

{% code overflow="wrap" %}

```bash
export GORGIAS='{ type: api, spec: gorgias, secrets: { subdomain: "mycompany", email: "user@example.com", api_key: "xxxxxxxxxxxxxxxx" } }'
```

{% 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:
  GORGIAS:
    type: api
    spec: gorgias
    secrets:
      subdomain: "mycompany"
      email: "user@example.com"
      api_key: "xxxxxxxxxxxxxxxx"
```

**With anchor date for historical data:**

```yaml
connections:
  GORGIAS:
    type: api
    spec: gorgias
    secrets:
      subdomain: "mycompany"
      email: "user@example.com"
      api_key: "xxxxxxxxxxxxxxxx"
    inputs:
      anchor_date: "2024-01-01"
```

## Replication

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

```yaml
source: GORGIAS
target: MY_POSTGRES

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

streams:
  # Core support data
  tickets:
    mode: incremental
  ticket_messages:
  customers:
    mode: incremental

  # Configuration data
  users:
  teams:
  tags:
  macros:
  rules:
  custom_fields:
  satisfaction_surveys:
```

**Sync all endpoints:**

```yaml
source: GORGIAS
target: MY_POSTGRES

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

streams:
  '*':
```

## Endpoints

### Core Support Data

| Endpoint               | Description                              | Incremental        |
| ---------------------- | ---------------------------------------- | ------------------ |
| `tickets`              | Support tickets                          | Yes (cursor-based) |
| `ticket_messages`      | Messages within tickets (child endpoint) | No                 |
| `customers`            | Customer profiles                        | Yes (cursor-based) |
| `satisfaction_surveys` | Customer satisfaction survey responses   | Yes (cursor-based) |

### Users & Teams

| Endpoint | Description             | Incremental |
| -------- | ----------------------- | ----------- |
| `users`  | Team members and agents | No          |
| `teams`  | Team groupings          | No          |

### Configuration

| Endpoint        | Description                            | Incremental |
| --------------- | -------------------------------------- | ----------- |
| `tags`          | Ticket categorization tags             | No          |
| `macros`        | Pre-made response templates            | No          |
| `rules`         | Automation rules                       | No          |
| `custom_fields` | Custom field definitions (ticket type) | No          |
| `views`         | Saved ticket views/filters             | No          |
| `integrations`  | Integration configurations             | No          |

### Account

| Endpoint  | Description                      | Incremental |
| --------- | -------------------------------- | ----------- |
| `account` | Account information and settings | No          |

### Events

| Endpoint | Description       | Incremental        |
| -------- | ----------------- | ------------------ |
| `events` | Event log entries | Yes (cursor-based) |

To discover available endpoints:

```bash
sling conns discover GORGIAS
```

## Incremental Sync

The Gorgias connector supports incremental sync for the following endpoints:

* **tickets** — Fetches all tickets using cursor-based pagination. Subsequent runs resume from the last cursor position.
* **customers** — Fetches all customer profiles using cursor-based pagination.
* **events** — Fetches event log entries ordered by creation date.
* **satisfaction\_surveys** — Fetches survey responses using cursor-based pagination.

### Anchor Date

On the first sync, incremental endpoints use the `anchor_date` input (default: 1 year ago) as the starting point. Subsequent syncs resume from the last cursor position.

### Child Endpoints

The `ticket_messages` endpoint uses a queue-based pattern:

1. First, the `tickets` endpoint runs and collects ticket IDs
2. Then, the `ticket_messages` endpoint iterates through the queue to fetch messages for each ticket

This means you should run the `tickets` endpoint before `ticket_messages` in your replication.

## Rate Limiting

The Gorgias API has rate limits:

* **API Key Auth:** 40 requests per 20-second window
* **OAuth2 Auth:** 80 requests per 20-second window

The connector automatically:

* Uses conservative rate limiting (2 requests/second)
* Retries with exponential backoff on rate limit responses (HTTP 429)

To check your current rate limit usage, look for the `X-Gorgias-Account-Api-Call-Limit` header in API responses.

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).