# Gorgias

> Helpdesk platform for managing support tickets, customer conversations, and tags across email, chat, and other channels.

Source: https://cotera.co/docs/reference/tools/individual-tools/gorgias

---

**Authentication Type:** API Key\
**Description:** Helpdesk platform for managing support tickets, customer conversations, and tags across email, chat, and other channels.

***

## Authentication

To authenticate, you'll need your Gorgias account subdomain (the `account` in `account.gorgias.com`), the email address of an agent or admin user, and an API key. Generate an API key from **Settings → REST API** in your Gorgias account. Learn more in the [Gorgias REST API documentation](https://developers.gorgias.com/docs/getting-started-with-gorgias-rest-api).

***

## Tickets

Read, create, and update support tickets, post replies and internal notes, and manage ticket tags.

### Get Ticket

Retrieve a single Gorgias support ticket by ID.

**Operation Type:** Query (Read)

**Parameters:**

* **ticketId** `number` (required): The Gorgias ticket ID

**Returns:**

* **ticket** `object`: The ticket record
  * **id** `number`: The ticket ID
  * **subject** `string` (nullable): The ticket subject
  * **status** `string`: The ticket status
  * **channel** `string`: The channel the ticket came in on
  * **priority** `string` (nullable): The ticket priority
  * **customer\_id** `number` (nullable): The ID of the requesting customer
  * **assignee\_user\_id** `number` (nullable): The ID of the assigned agent
  * **assignee\_team\_id** `number` (nullable): The ID of the assigned team
  * **tags** `array`: Tags applied to the ticket
    * **id** `number`: The tag ID
    * **name** `string`: The tag name
  * **created\_datetime** `string` (nullable): When the ticket was created
  * **updated\_datetime** `string` (nullable): When the ticket was last updated

**Example Usage:**

```json
{
  "ticketId": 12345
}
```

### Search Tickets

List or filter Gorgias support tickets with cursor pagination.

**Operation Type:** Query (Read)

**Parameters:**

* **customerId** `number` (nullable): Filter by customer ID
* **viewId** `number` (nullable): Filter to tickets in a specific view. Use a view to filter by status, channel, or other criteria — those are not query params on `/tickets`
* **externalId** `string` (nullable): Filter by external ID
* **orderBy** `string` (nullable): Sort order, e.g. `"updated_datetime:desc"`
* **limit** `number` (nullable): Page size (max 100, default 30)
* **cursor** `string` (nullable): Pagination cursor from a prior response

**Returns:**

* **tickets** `array`: The matching tickets
  * **id** `number`: The ticket ID
  * **subject** `string` (nullable): The ticket subject
  * **status** `string`: The ticket status
  * **channel** `string`: The channel the ticket came in on
  * **priority** `string` (nullable): The ticket priority
  * **customer\_id** `number` (nullable): The ID of the requesting customer
  * **assignee\_user\_id** `number` (nullable): The ID of the assigned agent
  * **assignee\_team\_id** `number` (nullable): The ID of the assigned team
  * **tags** `array`: Tags applied to the ticket
    * **id** `number`: The tag ID
    * **name** `string`: The tag name
  * **created\_datetime** `string` (nullable): When the ticket was created
  * **updated\_datetime** `string` (nullable): When the ticket was last updated
* **nextCursor** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "customerId": 98765,
  "orderBy": "updated_datetime:desc",
  "limit": 50
}
```

### Create Ticket

Create a new Gorgias support ticket with an initial message.

**Operation Type:** Mutation (Write)

**Parameters:**

* **channel** `string` (required): Channel for the initial message (email, chat, sms, phone, etc.)
* **customerId** `number` (required): Existing Gorgias customer ID for the requester
* **fromAgent** `boolean` (required): Whether the initial message is authored by an agent (true) or the customer (false)
* **subject** `string` (nullable): Ticket subject
* **bodyText** `string` (nullable): Plain-text body of the initial message
* **bodyHtml** `string` (nullable): HTML body of the initial message
* **senderUserId** `number` (nullable): Agent user ID (required when `fromAgent` is true; ignored otherwise)
* **status** `string` (nullable): Initial ticket status (open, closed). Defaults to open
* **fromEmail** `string` (nullable): Sender email address. Required for email-channel tickets — Gorgias rejects messages without `source.from`. For `fromAgent=true` use the agent email; for `fromAgent=false` use the customer email
* **fromName** `string` (nullable): Sender display name (optional)
* **toEmail** `string` (nullable): Recipient email address. Recommended for email-channel tickets. For `fromAgent=true` use the customer email; for `fromAgent=false` use the support inbox
* **toName** `string` (nullable): Recipient display name (optional)

**Returns:**

* **ticketId** `number`: The ID of the created ticket
* **status** `string`: The ticket status
* **channel** `string`: The channel of the initial message
* **createdDatetime** `string` (nullable): When the ticket was created

**Example Usage:**

```json
{
  "channel": "email",
  "customerId": 98765,
  "fromAgent": false,
  "subject": "Order hasn't shipped yet",
  "bodyText": "Hi, I placed order #1042 five days ago and it still shows as processing. Can you check on this?",
  "fromEmail": "customer@example.com",
  "toEmail": "support@yourstore.com"
}
```

### Update Ticket

Update a Gorgias ticket — status, priority, assignee, or subject.

**Operation Type:** Mutation (Write)

**Parameters:**

* **ticketId** `number` (required): Ticket ID to update
* **status** `string` (nullable): New status. Must be exactly `"open"` or `"closed"`
* **priority** `string` (nullable): New priority. Must be exactly one of `"critical"`, `"high"`, `"normal"`, `"low"`
* **assigneeUserId** `number` (nullable): Agent user ID to assign the ticket to
* **assigneeTeamId** `number` (nullable): Team ID to assign the ticket to
* **subject** `string` (nullable): New ticket subject

**Returns:**

* **ticketId** `number`: The ID of the updated ticket
* **status** `string`: The ticket status
* **priority** `string` (nullable): The ticket priority
* **assignee\_user\_id** `number` (nullable): The ID of the assigned agent
* **assignee\_team\_id** `number` (nullable): The ID of the assigned team
* **updated\_datetime** `string` (nullable): When the ticket was last updated

**Example Usage:**

```json
{
  "ticketId": 12345,
  "status": "closed",
  "priority": "high",
  "assigneeUserId": 4567
}
```

### Reply to Ticket

Post a customer-facing reply to a Gorgias ticket on its channel.

**Operation Type:** Mutation (Write)

**Parameters:**

* **ticketId** `number` (required): Ticket to reply to
* **channel** `string` (required): Channel for the reply (email, chat, sms, etc.) — usually matches the ticket channel
* **senderUserId** `number` (required): Agent user ID sending the reply
* **bodyText** `string` (nullable): Plain-text body of the reply
* **bodyHtml** `string` (nullable): HTML body of the reply
* **receiverCustomerId** `number` (nullable): Customer ID receiving the reply
* **fromEmail** `string` (nullable): Sender email address. Required for email-channel replies — Gorgias rejects messages without `source.from`
* **fromName** `string` (nullable): Sender display name (optional)
* **toEmail** `string` (nullable): Recipient email address. Recommended for email-channel replies so Gorgias knows where to deliver
* **toName** `string` (nullable): Recipient display name (optional)

**Returns:**

* **messageId** `number`: The ID of the created message
* **ticketId** `number`: The ID of the ticket
* **channel** `string`: The channel of the reply
* **public** `boolean`: Whether the message is customer-facing
* **createdDatetime** `string` (nullable): When the reply was created

**Example Usage:**

```json
{
  "ticketId": 12345,
  "channel": "email",
  "senderUserId": 4567,
  "bodyText": "Thanks for reaching out! I've located order #1042 and reshipped it with expedited delivery — you should receive it within 2 business days.",
  "receiverCustomerId": 98765,
  "fromEmail": "support@yourstore.com",
  "toEmail": "customer@example.com"
}
```

### Add Internal Note

Add an internal note to a Gorgias ticket — only visible to agents.

**Operation Type:** Mutation (Write)

**Parameters:**

* **ticketId** `number` (required): Ticket to add the note to
* **senderUserId** `number` (required): Agent user ID authoring the note
* **bodyText** `string` (nullable): Plain-text body of the note
* **bodyHtml** `string` (nullable): HTML body of the note

At least one of `bodyText` or `bodyHtml` must be provided.

**Returns:**

* **messageId** `number`: The ID of the created note
* **ticketId** `number`: The ID of the ticket
* **createdDatetime** `string` (nullable): When the note was created

**Example Usage:**

```json
{
  "ticketId": 12345,
  "senderUserId": 4567,
  "bodyText": "Customer is a VIP — reshipped at no charge and flagged the account for follow-up next week."
}
```

### Get Ticket Messages

Retrieve the messages (conversation thread) for a Gorgias ticket.

**Operation Type:** Query (Read)

**Parameters:**

* **ticketId** `number` (required): Ticket ID whose messages to retrieve
* **limit** `number` (nullable): Page size (max 100, default 30)
* **cursor** `string` (nullable): Pagination cursor from a prior response

**Returns:**

* **messages** `array`: The messages in the ticket thread
  * **id** `number`: The message ID
  * **ticket\_id** `number`: The ID of the parent ticket
  * **channel** `string`: The channel the message was sent on
  * **via** `string` (nullable): How the message was created
  * **from\_agent** `boolean`: Whether the message was authored by an agent
  * **public** `boolean`: Whether the message is customer-facing
  * **body\_text** `string` (nullable): Plain-text body of the message
  * **body\_html** `string` (nullable): HTML body of the message
  * **sender\_id** `number` (nullable): The ID of the sender
  * **sender\_type** `string` (nullable): The type of sender
  * **created\_datetime** `string` (nullable): When the message was created
  * **attachments** `array`: Files attached to the message
    * **url** `string` (nullable): The attachment URL
    * **name** `string` (nullable): The attachment file name
    * **content\_type** `string` (nullable): The MIME type of the attachment
    * **size** `number` (nullable): The attachment size in bytes
    * **public** `boolean` (nullable): Whether the attachment is customer-facing
* **nextCursor** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "ticketId": 12345,
  "limit": 50
}
```

### List Ticket Tags

List the tags currently applied to a Gorgias ticket.

**Operation Type:** Query (Read)

**Parameters:**

* **ticketId** `number` (required): Ticket whose tags to list

**Returns:**

* **tags** `array`: The tags applied to the ticket
  * **id** `number`: The tag ID
  * **name** `string`: The tag name
  * **description** `string` (nullable): The tag description
  * **color** `string` (nullable): The tag color

**Example Usage:**

```json
{
  "ticketId": 12345
}
```

### Add Ticket Tags

Add one or more tags to a Gorgias ticket without replacing existing tags. Identify tags by name (creating them if absent) or by ID.

**Operation Type:** Mutation (Write)

**Parameters:**

* **ticketId** `number` (required): Ticket to tag
* **tagNames** `array` of `string` (nullable): Names of tags to add. Tags are created if they do not exist. Provide `tagNames`, `tagIds`, or both
* **tagIds** `array` of `number` (nullable): IDs of existing tags to add. Provide `tagNames`, `tagIds`, or both

**Returns:**

* **success** `boolean`: Whether the tags were added successfully. Use List Ticket Tags to fetch the resulting tag set if needed

**Example Usage:**

```json
{
  "ticketId": 12345,
  "tagNames": ["vip", "reshipped"]
}
```

***

## Customers

Look up customer records in Gorgias.

### Find Customer by Email

Look up Gorgias customers by their email address.

**Operation Type:** Query (Read)

**Parameters:**

* **email** `string` (required): Email address to search for

**Returns:**

* **customers** `array`: The matching customers
  * **id** `number`: The customer ID
  * **name** `string` (nullable): The customer's full name
  * **firstname** `string` (nullable): The customer's first name
  * **lastname** `string` (nullable): The customer's last name
  * **email** `string` (nullable): The customer's email address
  * **external\_id** `string` (nullable): The customer's external ID
  * **created\_datetime** `string` (nullable): When the customer was created

**Example Usage:**

```json
{
  "email": "customer@example.com"
}
```

***

## Common Use Cases

**Ticket Triage & Routing:**

* Search tickets by customer, view, or external ID to surface what needs attention
* Update status, priority, and assignee to route tickets to the right agent or team
* Tag tickets by topic, severity, or workflow stage for filtering and reporting

**Customer Support Automation:**

* Create tickets on behalf of customers or agents across email, chat, and SMS
* Post customer-facing replies and resolve conversations programmatically
* Pull the full message thread, including attachments, for context and summarization

**Internal Collaboration:**

* Add agent-only internal notes to document context and hand-offs
* Look up customers by email to link conversations to the right account
* List and apply tags to keep ticket organization consistent across the team