Support Tickets API

Learn how to manage customer support tickets in AchieveApex using the REST API.

Overview

The Support Tickets API allows you to manage customer support tickets within your organization. You can list, retrieve, create, update, and delete tickets, as well as manage ticket messages and assignments.

Base Endpoint

/support-tickets

Support Ticket Object

The support ticket object contains information about a customer support inquiry including its status, priority, and assignment details.

Support Ticket Object
{
  "id": 123,
  "organization_id": 27,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@company.com",
  "contact_id": 456,
  "meta_contact_first_name": "John",
  "meta_contact_last_name": "Doe",
  "reference_number": "TK-2023-001",
  "subject": "Cannot access my account",
  "status": "open",
  "priority": "high",
  "tags": ["login", "access"],
  "meta_contact_email": "john.doe@example.com",
  "assigned_user_id": 789,
  "assigned_ai_assistant_id": null,
  "thread_id": "thread_abc123",
  "last_message_at": "2023-05-15T10:45:20.391Z",
  "handoff_reason": null,
  "created_at": "2023-05-15T10:45:20.391Z",
  "updated_at": "2023-05-15T11:30:15.471Z",
  "deleted_at": null
}

List Support Tickets

Retrieve a list of support tickets in your organization with optional filtering and pagination.

Request
GET /support-tickets

curl -X GET https://api.achieveapex.com/support-tickets \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 27,
      "$limit": 10,
      "$skip": 0,
      "$sort": { "created_at": -1 }
    }
  }'
Response
{
  "total": 15,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "organization_id": 27,
      "inbox_channel_id": 5,
      "channel": "gmail",
      "meta_inbox_channel_email": "support@company.com",
      "contact_id": 456,
      "meta_contact_first_name": "John",
      "meta_contact_last_name": "Doe",
      "reference_number": "TK-2023-001",
      "subject": "Cannot access my account",
      "status": "open",
      "priority": "high",
      "tags": ["login", "access"],
      "meta_contact_email": "john.doe@example.com",
      "assigned_user_id": 789,
      "assigned_ai_assistant_id": null,
      "thread_id": "thread_abc123",
      "last_message_at": "2023-05-15T10:45:20.391Z",
      "handoff_reason": null,
      "created_at": "2023-05-15T10:45:20.391Z",
      "updated_at": "2023-05-15T11:30:15.471Z",
      "deleted_at": null
    },
    {
      "id": 124,
      "organization_id": 27,
      "inbox_channel_id": 5,
      "channel": "gmail",
      "meta_inbox_channel_email": "support@company.com",
      "contact_id": 457,
      "meta_contact_first_name": "Jane",
      "meta_contact_last_name": "Smith",
      "reference_number": "TK-2023-002",
      "subject": "Billing error on subscription",
      "status": "pending",
      "priority": "medium",
      "tags": ["billing", "subscription"],
      "meta_contact_email": "jane.smith@example.com",
      "assigned_user_id": 790,
      "assigned_ai_assistant_id": null,
      "thread_id": "thread_def456",
      "last_message_at": "2023-05-14T16:22:10.123Z",
      "handoff_reason": null,
      "created_at": "2023-05-14T16:20:30.552Z",
      "updated_at": "2023-05-14T18:15:45.788Z",
      "deleted_at": null
    }
  ]
}

Query Parameters

ParameterTypeDescription
organization_idNumberID of the organization (required)
statusStringFilter by status ("open", "pending", "closed", "waiting_customer")
priorityStringFilter by priority ("low", "medium", "high", "urgent")
assigned_user_idNumberFilter by assigned user ID
assigned_ai_assistant_idNumberFilter by assigned AI assistant ID
contact_idNumberFilter by contact ID
inbox_channel_idNumberFilter by inbox channel ID
tagsArrayFilter by tags
$limitNumberNumber of tickets to return (default: 10)
$skipNumberNumber of tickets to skip (for pagination)
$sortObjectSort criteria (e.g., { "created_at": -1 } for newest first)

Get a Support Ticket

Retrieve a single support ticket by ID.

Request
GET /support-tickets/:id

curl -X GET https://api.achieveapex.com/support-tickets/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
Response
{
  "id": 123,
  "organization_id": 27,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@company.com",
  "contact_id": 456,
  "meta_contact_first_name": "John",
  "meta_contact_last_name": "Doe",
  "reference_number": "TK-2023-001",
  "subject": "Cannot access my account",
  "status": "open",
  "priority": "high",
  "tags": ["login", "access"],
  "meta_contact_email": "john.doe@example.com",
  "assigned_user_id": 789,
  "assigned_ai_assistant_id": null,
  "thread_id": "thread_abc123",
  "last_message_at": "2023-05-15T10:45:20.391Z",
  "handoff_reason": null,
  "created_at": "2023-05-15T10:45:20.391Z",
  "updated_at": "2023-05-15T11:30:15.471Z",
  "deleted_at": null,
  "contact": {
    "id": 456,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "assigned_user": {
    "id": 789,
    "first_name": "Support",
    "last_name": "Agent"
  },
  "inbox_channel": {
    "id": 5,
    "name": "General Support",
    "email": "support@company.com"
  }
}

Create a Support Ticket

Create a new support ticket in your organization.

Request
POST /support-tickets

curl -X POST https://api.achieveapex.com/support-tickets \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "inbox_channel_id": 5,
    "contact_id": 456,
    "subject": "Need help with integration",
    "priority": "medium",
    "tags": ["integration", "api"],
    "status": "open"
  }'
Response
{
  "id": 125,
  "organization_id": 27,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@company.com",
  "contact_id": 456,
  "meta_contact_first_name": "John",
  "meta_contact_last_name": "Doe",
  "reference_number": "TK-2023-003",
  "subject": "Need help with integration",
  "status": "open",
  "priority": "medium",
  "tags": ["integration", "api"],
  "meta_contact_email": "john.doe@example.com",
  "assigned_user_id": null,
  "assigned_ai_assistant_id": null,
  "thread_id": "thread_ghi789",
  "last_message_at": "2023-05-16T09:12:33.215Z",
  "handoff_reason": null,
  "created_at": "2023-05-16T09:12:33.215Z",
  "updated_at": "2023-05-16T09:12:33.215Z",
  "deleted_at": null
}

Update a Support Ticket

Update an existing support ticket in your organization.

Request
PATCH /support-tickets/:id

curl -X PATCH https://api.achieveapex.com/support-tickets/125 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "pending",
    "priority": "high",
    "assigned_user_id": 789,
    "tags": ["integration", "api", "urgent"]
  }'
Response
{
  "id": 125,
  "organization_id": 27,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@company.com",
  "contact_id": 456,
  "meta_contact_first_name": "John",
  "meta_contact_last_name": "Doe",
  "reference_number": "TK-2023-003",
  "subject": "Need help with integration",
  "status": "pending",
  "priority": "high",
  "tags": ["integration", "api", "urgent"],
  "meta_contact_email": "john.doe@example.com",
  "assigned_user_id": 789,
  "assigned_ai_assistant_id": null,
  "thread_id": "thread_ghi789",
  "last_message_at": "2023-05-16T09:12:33.215Z",
  "handoff_reason": null,
  "created_at": "2023-05-16T09:12:33.215Z",
  "updated_at": "2023-05-16T09:30:45.127Z",
  "deleted_at": null
}

Delete a Support Ticket

Delete a support ticket from your organization.

Request
DELETE /support-tickets/:id

curl -X DELETE https://api.achieveapex.com/support-tickets/125 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response
{
  "id": 125,
  "organization_id": 27,
  "inbox_channel_id": 5,
  "channel": "gmail",
  "meta_inbox_channel_email": "support@company.com",
  "contact_id": 456,
  "meta_contact_first_name": "John",
  "meta_contact_last_name": "Doe",
  "reference_number": "TK-2023-003",
  "subject": "Need help with integration",
  "status": "pending",
  "priority": "high",
  "tags": ["integration", "api", "urgent"],
  "meta_contact_email": "john.doe@example.com",
  "assigned_user_id": 789,
  "assigned_ai_assistant_id": null,
  "thread_id": "thread_ghi789",
  "last_message_at": "2023-05-16T09:12:33.215Z",
  "handoff_reason": null,
  "created_at": "2023-05-16T09:12:33.215Z",
  "updated_at": "2023-05-16T10:15:22.554Z",
  "deleted_at": "2023-05-16T10:15:22.554Z"
}

Note on Ticket Deletion

When a ticket is deleted, the system performs a soft delete by setting the deleted_at timestamp. The ticket will no longer appear in ticket listings but its data is preserved for record-keeping purposes.

Batch Actions

Perform actions on multiple tickets at once.

Request
POST /support-tickets-batch-actions

curl -X POST https://api.achieveapex.com/support-tickets-batch-actions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "ticket_ids": [123, 124, 125],
    "action": "update",
    "data": {
      "status": "closed"
    }
  }'
Response
{
  "success": true,
  "count": 3,
  "failed": []
}

Import Support Tickets

Import multiple support tickets in bulk.

Request
POST /import-support-tickets

curl -X POST https://api.achieveapex.com/import-support-tickets \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 27,
    "support_tickets": {
      "subject": "Customer complaint about delivery",
      "status": "open",
      "priority": "high",
      "tags": ["delivery", "complaint"]
    },
    "contacts": {
      "first_name": "Sarah",
      "last_name": "Johnson",
      "email": "sarah.johnson@example.com",
      "phone": "+1234567890"
    },
    "ticket_messages_email": {
      "text_content": "My order #12345 was supposed to arrive yesterday but I haven't received it yet. Please help!",
      "destination": "incoming"
    }
  }'
Response
{
  "id": 126,
  "organization_id": 27,
  "contact_id": 458,
  "subject": "Customer complaint about delivery",
  "status": "open",
  "priority": "high",
  "tags": ["delivery", "complaint"],
  "reference_number": "TK-2023-004",
  "meta_contact_email": "sarah.johnson@example.com",
  "meta_contact_first_name": "Sarah",
  "meta_contact_last_name": "Johnson",
  "created_at": "2023-05-16T14:25:10.331Z",
  "updated_at": "2023-05-16T14:25:10.331Z",
  "message": {
    "id": 42,
    "ticket_id": 126,
    "text_content": "My order #12345 was supposed to arrive yesterday but I haven't received it yet. Please help!",
    "destination": "incoming",
    "created_at": "2023-05-16T14:25:10.345Z"
  }
}

Ticket Messages

Ticket messages represent the conversation history within a support ticket.

Get Ticket Messages

Request
GET /ticket-messages-gmail

curl -X GET https://api.achieveapex.com/ticket-messages-gmail \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "ticket_id": 123,
      "$sort": { "created_at": 1 },
      "$limit": 100
    }
  }'

Ticket Message Object

Ticket Message Object
{
  "_id": "msg123",
  "organization_id": 27,
  "ticket_id": 123,
  "message_id": "email123456",
  "thread_id": "thread_abc123",
  "history_id": "hist78901",
  "message_type": "email",
  "destination": "incoming",
  "subject": "Cannot access my account",
  "text_content": "Hello, I'm having trouble logging into my account. It says my password is incorrect, but I'm sure I'm using the right one.",
  "html_content": "<div>Hello, I'm having trouble logging into my account. It says my password is incorrect, but I'm sure I'm using the right one.</div>",
  "from_email": "john.doe@example.com",
  "from_name": "John Doe",
  "to_email": "support@company.com",
  "to_name": "Support Team",
  "cc": [],
  "bcc": [],
  "attachments": [],
  "labels": ["inbox", "unread"],
  "read": false,
  "internal_date": "2023-05-15T10:45:20.391Z",
  "created_at": "2023-05-15T10:45:20.391Z",
  "updated_at": "2023-05-15T10:45:20.391Z",
  "deleted_at": null
}

Error Handling

The Support Tickets API returns standard HTTP status codes and error messages.

Error Response
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
Status CodeDescription
400 Bad RequestInvalid parameters or request
401 UnauthorizedMissing or invalid authentication
403 ForbiddenNot authorized to access this organization's tickets
404 Not FoundTicket not found
500 Internal Server ErrorServer error

Related Documentation

For information on managing contacts associated with tickets, see the Contacts API documentation.

Report an issue with this documentation

Please log in to report issues with our documentation.