Tickets

Tickets are the core of Support Station - they represent customer support requests and conversations. On this page, we will dive into the different ticket endpoints you can use to manage tickets programmatically. We will look at how to create, retrieve, update, and list tickets.

The ticket model

The ticket model contains all the information about a support ticket, including the subject, status, priority, customer information, and messages.

Properties

Name
id
Type
string
Description
Unique identifier for the ticket (UUID).
Name
ticket_number
Type
integer
Description
Human-readable ticket number, auto-incremented per organization.
Name
subject
Type
string
Description
The ticket subject line (max 500 characters).
Name
status
Type
string
Description
Current status: OPEN, PENDING, ON_HOLD, RESOLVED, or CLOSED.
Name
priority
Type
string
Description
Priority level: LOW, MEDIUM, HIGH, or URGENT.
Name
channel
Type
string
Description
How the ticket was created: API, EMAIL, EMBED, or MANUAL.
Name
customer
Type
object
Description
The customer who created the ticket.
Name
assignee
Type
object
Description
The support agent assigned to the ticket (nullable).
Name
team
Type
object
Description
The team assigned to handle the ticket (nullable).
Name
tags
Type
array
Description
Array of tags applied to the ticket.
Name
messages
Type
array
Description
Array of messages in the ticket conversation.
Name
created_at
Type
timestamp
Description
Timestamp of when the ticket was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the ticket was last updated.
Name
closed_at
Type
timestamp
Description
Timestamp of when the ticket was closed (nullable).

POST/api/v1/tickets

Create a ticket

Creates a new ticket with an initial message. If the customer does not exist, they will be created automatically based on the provided email.

Required scope: tickets:write

Required attributes

Name
subject
Type
string
Description
The ticket subject (max 500 characters).
Name
message
Type
string
Description
The initial message content from the customer.
Name
customer
Type
object
Description
Customer information. Must include email.
Name
customer.email
Type
string
Description
Customer email address (required).

Optional attributes

Name
priority
Type
string
Description
Priority level: LOW, MEDIUM (default), HIGH, or URGENT.
Name
tag_ids
Type
string[]
Description
Array of tag UUIDs to apply to the ticket.
Name
customer.name
Type
string
Description
Customer display name.
Name
customer.external_user_id
Type
string
Description
Your system user ID for this customer.
Name
customer.external_organization_id
Type
string
Description
Your system organization/company ID.
Name
customer.metadata
Type
object
Description
Arbitrary JSON metadata to store with the customer.

Request

POST

/api/v1/tickets

curl -X POST https://api.supportstation.io/api/v1/tickets \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Help with login",
    "message": "I am unable to log into my account.",
    "priority": "MEDIUM",
    "customer": {
      "email": "john@example.com",
      "name": "John Doe"
    }
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "ticket_number": 42,
    "subject": "Help with login",
    "status": "OPEN",
    "priority": "MEDIUM",
    "channel": "API",
    "customer": {
      "id": "customer-uuid",
      "email": "john@example.com",
      "name": "John Doe"
    },
    "assignee": null,
    "team": null,
    "tags": [],
    "messages": [
      {
        "id": "message-uuid",
        "content": "I am unable to log into my account.",
        "type": "INBOUND",
        "created_at": "2025-01-15T10:30:00.000Z"
      }
    ],
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "closed_at": null
  }
}

GET/api/v1/tickets

List all tickets

Returns a paginated list of tickets in your organization.

Required scope: tickets:read

Query parameters

Name
page
Type
integer
Description
Page number (default: 1).
Name
limit
Type
integer
Description
Items per page, max 100 (default: 20).
Name
status
Type
string
Description
Filter by status: OPEN, PENDING, ON_HOLD, RESOLVED, CLOSED.
Name
priority
Type
string
Description
Filter by priority: LOW, MEDIUM, HIGH, URGENT.
Name
customer_id
Type
string
Description
Filter by customer UUID.
Name
assignee_id
Type
string
Description
Filter by assignee UUID.
Name
tag_id
Type
string
Description
Filter by tag UUID.
Name
search
Type
string
Description
Search in subject, customer email, or customer name.

Request

GET

/api/v1/tickets

curl -G https://api.supportstation.io/api/v1/tickets \
  -H "Authorization: Bearer {token}" \
  -d status=OPEN \
  -d limit=20

Response

{
  "data": [
    {
      "id": "ticket-uuid",
      "ticket_number": 42,
      "subject": "Help with login",
      "status": "OPEN",
      "priority": "MEDIUM",
      "channel": "API",
      "customer": {
        "id": "customer-uuid",
        "email": "john@example.com",
        "name": "John Doe"
      },
      "assignee": null,
      "team": null,
      "tags": [],
      "message_count": 3,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "total_pages": 8
    }
  }
}

GET/api/v1/tickets/:id

Retrieve a ticket

Returns a single ticket with all messages.

Required scope: tickets:read

Request

GET

/api/v1/tickets/:id

curl https://api.supportstation.io/api/v1/tickets/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "ticket-uuid",
    "ticket_number": 42,
    "subject": "Help with login",
    "status": "OPEN",
    "priority": "MEDIUM",
    "channel": "API",
    "customer": {
      "id": "customer-uuid",
      "email": "john@example.com",
      "name": "John Doe"
    },
    "assignee": {
      "id": "user-uuid",
      "name": "Support Agent",
      "email": "agent@company.com"
    },
    "team": {
      "id": "team-uuid",
      "name": "Technical Support"
    },
    "tags": [
      {
        "id": "tag-uuid",
        "name": "bug",
        "color": "red"
      }
    ],
    "messages": [
      {
        "id": "message-uuid",
        "content": "I am unable to log into my account.",
        "type": "INBOUND",
        "author": {
          "type": "customer",
          "id": "customer-uuid",
          "email": "john@example.com",
          "name": "John Doe"
        },
        "created_at": "2025-01-15T10:30:00.000Z"
      }
    ],
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T11:00:00.000Z",
    "closed_at": null
  }
}

POST/api/v1/tickets/:id/messages

Add a message to a ticket

Adds a new message to an existing ticket. By default, messages are recorded as customer replies (INBOUND). To add a message as a support staff member, include the user_id parameter.

Required scope: tickets:write

Required attributes

Name
content
Type
string
Description
The message content.

Optional attributes

Name
user_id
Type
string
Description
UUID of the support staff member sending the message. If provided, the message will be recorded as an OUTBOUND (staff) reply. If omitted, the message is recorded as an INBOUND (customer) reply.

Customer message

POST

/api/v1/tickets/:id/messages

curl -X POST https://api.supportstation.io/api/v1/tickets/550e8400-e29b-41d4-a716-446655440000/messages \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Thanks for the help! The issue is now resolved."
  }'

Customer response

{
  "data": {
    "id": "message-uuid",
    "content": "Thanks for the help! The issue is now resolved.",
    "type": "INBOUND",
    "author": {
      "type": "customer",
      "id": "customer-uuid",
      "email": "john@example.com",
      "name": "John Doe"
    },
    "created_at": "2025-01-15T14:00:00.000Z"
  }
}

Staff message

POST

/api/v1/tickets/:id/messages

curl -X POST https://api.supportstation.io/api/v1/tickets/550e8400-e29b-41d4-a716-446655440000/messages \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hi John, I have looked into this and reset your account. Please try logging in again.",
    "user_id": "user-uuid"
  }'

Staff response

{
  "data": {
    "id": "message-uuid",
    "content": "Hi John, I have looked into this and reset your account. Please try logging in again.",
    "type": "OUTBOUND",
    "author": {
      "type": "user",
      "id": "user-uuid",
      "email": "agent@company.com",
      "name": "Support Agent"
    },
    "created_at": "2025-01-15T14:30:00.000Z"
  }
}

PATCH/api/v1/tickets/:id

Update a ticket

Updates ticket properties like status, priority, assignee, or tags.

Required scope: tickets:write

Optional attributes

Name
status
Type
string
Description
New status: OPEN, PENDING, ON_HOLD, RESOLVED, CLOSED.
Name
priority
Type
string
Description
New priority: LOW, MEDIUM, HIGH, URGENT.
Name
subject
Type
string
Description
Updated subject (max 500 characters).
Name
assignee_id
Type
string | null
Description
User UUID to assign the ticket to, or null to unassign.
Name
add_tag_ids
Type
string[]
Description
Array of tag UUIDs to add to the ticket.
Name
remove_tag_ids
Type
string[]
Description
Array of tag UUIDs to remove from the ticket.

Request

PATCH

/api/v1/tickets/:id

curl -X PATCH https://api.supportstation.io/api/v1/tickets/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "RESOLVED",
    "priority": "LOW"
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "ticket_number": 42,
    "subject": "Help with login",
    "status": "RESOLVED",
    "priority": "LOW",
    "channel": "API",
    "customer": {
      "id": "customer-uuid",
      "email": "john@example.com",
      "name": "John Doe"
    },
    "assignee": null,
    "team": null,
    "tags": [],
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T15:00:00.000Z",
    "closed_at": null
  }
}