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.

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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