> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ticketing API

> Create and manage support tickets programmatically

Complete API reference for ticket creation and management in AGO.

## Overview

The Ticketing API enables programmatic ticket creation and management. All endpoints require authentication via API key or session token.

**Base URL:** `https://your-domain.com/api`

***

## User-Facing Endpoints

### Create Ticket

Create a new support ticket.

**Endpoint:** `POST /ticketing/create-ticket`

**Authentication:** User session or API key

**Request Body:**

| Field            | Type   | Required | Description                                |
| ---------------- | ------ | -------- | ------------------------------------------ |
| `subject`        | string | Yes\*    | Ticket subject/title                       |
| `body`           | string | No       | Ticket description                         |
| `typology`       | string | No       | Ticket type (question, task, incident)     |
| `priority`       | string | No       | Priority level (low, normal, high, urgent) |
| `customFields`   | array  | No       | Custom field values                        |
| `files`          | array  | No       | File attachments                           |
| `user_email`     | string | No       | Override email for widget users            |
| `metadata`       | object | No       | Additional JSON metadata                   |
| `ticket_form_id` | string | No       | Specific form to use                       |
| `thread_id`      | string | No       | Link to conversation thread                |

\*Subject may be optional depending on form configuration

**Custom Fields Format:**

```json theme={null}
{
  "customFields": [
    {"id": "field_external_id", "value": "field_value"},
    {"id": "category", "value": "technical"},
    {"id": "product", "value": "product_a"}
  ]
}
```

**Example Request:**

```bash theme={null}
curl -X POST "https://your-domain.com/api/ticketing/create-ticket" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Cannot login to dashboard",
    "body": "I am receiving an authentication error when trying to access the admin dashboard.",
    "typology": "incident",
    "priority": "high",
    "customFields": [
      {"id": "category", "value": "authentication"},
      {"id": "browser", "value": "chrome"}
    ]
  }'
```

**Success Response (201):**

```json theme={null}
{
  "success": true,
  "ticket": {
    "id": 123,
    "external_id": "12345",
    "subject": "Cannot login to dashboard",
    "status": "open",
    "priority": "high",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

**Error Response (400/403):**

```json theme={null}
{
  "success": false,
  "error": "User not allowed to create tickets",
  "code": "PERMISSION_DENIED"
}
```

***

## Admin Endpoints

All admin endpoints require staff or admin authentication.

### List Tickets

Retrieve tickets with filtering and pagination.

**Endpoint:** `GET /admin/tickets`

**Query Parameters:**

| Parameter         | Type     | Description                            |
| ----------------- | -------- | -------------------------------------- |
| `page`            | integer  | Page number (default: 1)               |
| `page_size`       | integer  | Items per page (default: 20, max: 100) |
| `status`          | string   | Filter by status                       |
| `priority`        | string   | Filter by priority                     |
| `typology`        | string   | Filter by typology                     |
| `search`          | string   | Search in subject/body                 |
| `created_after`   | datetime | Filter by creation date                |
| `created_before`  | datetime | Filter by creation date                |
| `organization_id` | string   | Filter by organization                 |

**Example Request:**

```bash theme={null}
curl -X GET "https://your-domain.com/api/admin/tickets?status=open&priority=high&page=1" \
  -H "Authorization: Bearer admin-token"
```

**Response:**

```json theme={null}
{
  "count": 45,
  "next": "/api/admin/tickets?page=2",
  "previous": null,
  "results": [
    {
      "id": 123,
      "subject": "Login issue",
      "status": "open",
      "priority": "high",
      "typology": "incident",
      "requester": {
        "id": 456,
        "email": "user@example.com",
        "name": "John Doe"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ]
}
```

### Get Ticket Detail

Retrieve a single ticket with full details.

**Endpoint:** `GET /admin/tickets/{ticket_id}`

**Response:**

```json theme={null}
{
  "id": 123,
  "subject": "Login issue",
  "body": "Full ticket description...",
  "status": "open",
  "priority": "high",
  "typology": "incident",
  "external_id": "12345",
  "requester": {
    "id": 456,
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "organization": {
    "id": 789,
    "name": "Acme Corp"
  },
  "field_values": [
    {"field_id": "category", "value": "authentication"},
    {"field_id": "browser", "value": "chrome"}
  ],
  "thread_url": "https://ago.example.com/thread/abc123",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}
```

### Update Ticket Status

Change a ticket's status.

**Endpoint:** `PATCH /admin/tickets/{ticket_id}/status`

**Request Body:**

```json theme={null}
{
  "status_id": 2
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "ticket": {
    "id": 123,
    "status": "in_progress",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}
```

### List Ticket Statuses

Get available ticket statuses.

**Endpoint:** `GET /admin/tickets-statuses`

**Response:**

```json theme={null}
{
  "statuses": [
    {"id": 1, "name": "open", "label": "Open"},
    {"id": 2, "name": "in_progress", "label": "In Progress"},
    {"id": 3, "name": "pending", "label": "Pending"},
    {"id": 4, "name": "resolved", "label": "Resolved"},
    {"id": 5, "name": "closed", "label": "Closed"}
  ]
}
```

***

## Ticket Messages

### Add Message to Ticket

Send a message on a ticket.

**Endpoint:** `POST /admin/tickets/{ticket_id}/messages`

**Request Body:**

```json theme={null}
{
  "content": "Thank you for contacting us. We are investigating this issue.",
  "is_internal": false
}
```

| Field         | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `content`     | string  | Yes      | Message content                                  |
| `is_internal` | boolean | No       | If true, only visible to admins (default: false) |

**Response:**

```json theme={null}
{
  "success": true,
  "message": {
    "id": 789,
    "content": "Thank you for contacting us...",
    "is_internal": false,
    "sender": {
      "id": 101,
      "name": "Support Agent"
    },
    "created_at": "2024-01-15T12:30:00Z"
  }
}
```

### Get Ticket Messages

Retrieve all messages for a ticket.

**Endpoint:** `GET /admin/tickets/{ticket_id}/messages`

**Response:**

```json theme={null}
{
  "messages": [
    {
      "id": 788,
      "content": "I cannot login to the dashboard",
      "is_internal": false,
      "sender": {
        "id": 456,
        "name": "John Doe",
        "is_requester": true
      },
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": 789,
      "content": "Thank you for contacting us...",
      "is_internal": false,
      "sender": {
        "id": 101,
        "name": "Support Agent",
        "is_requester": false
      },
      "created_at": "2024-01-15T12:30:00Z"
    }
  ]
}
```

***

## Export & Statistics

### Export Tickets to CSV

Download tickets as a CSV file.

**Endpoint:** `GET /admin/export-tickets`

**Query Parameters:**

Same filters as List Tickets endpoint, plus:

| Parameter | Type   | Description                  |
| --------- | ------ | ---------------------------- |
| `format`  | string | Export format (default: csv) |

**Example:**

```bash theme={null}
curl -X GET "https://your-domain.com/api/admin/export-tickets?status=closed&created_after=2024-01-01" \
  -H "Authorization: Bearer admin-token" \
  -o tickets.csv
```

### Get Ticket Statistics

Retrieve dashboard statistics.

**Endpoint:** `GET /admin/tickets/stats`

**Response:**

```json theme={null}
{
  "total": 1250,
  "by_status": {
    "open": 45,
    "in_progress": 23,
    "pending": 12,
    "resolved": 870,
    "closed": 300
  },
  "by_priority": {
    "low": 200,
    "normal": 800,
    "high": 200,
    "urgent": 50
  },
  "created_today": 15,
  "created_this_week": 78,
  "average_resolution_time_hours": 4.5
}
```

***

## Ticket Forms

### List Ticket Forms

Get available ticket forms.

**Endpoint:** `GET /ticket-forms`

**Response:**

```json theme={null}
{
  "forms": [
    {
      "id": 1,
      "name": "General Support",
      "is_default": true
    },
    {
      "id": 2,
      "name": "Technical Support",
      "is_default": false
    }
  ]
}
```

### Get Default Form

Get the default ticket form configuration.

**Endpoint:** `GET /ticket-forms/default`

**Response:**

```json theme={null}
{
  "id": 1,
  "name": "General Support",
  "fields": [
    {
      "id": "subject",
      "type": "text",
      "label": "Subject",
      "required": true
    },
    {
      "id": "category",
      "type": "select",
      "label": "Category",
      "options": [...]
    }
  ],
  "show_subject": true,
  "show_body": true,
  "show_priority": true
}
```

### Get Active Ticketing System

Check which ticketing system is currently active.

**Endpoint:** `GET /ticket-forms/active-ticketing-system`

**Response:**

```json theme={null}
{
  "name": "zendesk",
  "active": true
}
```

***

## Error Codes

| Code                    | Description                                 |
| ----------------------- | ------------------------------------------- |
| `PERMISSION_DENIED`     | User not allowed to create tickets          |
| `INVALID_FORM`          | Form configuration error                    |
| `EXTERNAL_SYSTEM_ERROR` | Zendesk/HelpScout API error                 |
| `VALIDATION_ERROR`      | Invalid field values                        |
| `FILE_UPLOAD_ERROR`     | Attachment upload failed                    |
| `USER_NOT_FOUND`        | User not found in external system (Zendesk) |
| `TICKET_NOT_FOUND`      | Ticket ID does not exist                    |

***

## Rate Limiting

API requests are rate limited:

* **Standard endpoints:** 100 requests/minute
* **Export endpoints:** 10 requests/minute
* **Ticket creation:** 30 requests/minute

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320000
```

***

## Related Documentation

* [Ticketing System](../features/ticketing) - Complete ticketing documentation
* [Form Configuration](./form-configuration) - Form field configuration
* [Zendesk Integration](../data-connector/zendesk-ticketing-integration) - Zendesk setup
* [HelpScout Integration](../data-connector/helpscout-integration) - HelpScout setup