# 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](/sling-cli/cli-pro.md) or [Platform Plan](/sling-platform/platform.md).
{% 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/connections/api-connections/pages/eAdVs2BHCgdr6RS8GoJC#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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/gorgias.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.