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:

{
  "customFields": [
    {"id": "field_external_id", "value": "field_value"},
    {"id": "category", "value": "technical"},
    {"id": "product", "value": "product_a"}
  ]
}

Example Request:

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):

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

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

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

Response:

{
  "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": "[e-mail]",
        "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:

{
  "id": 123,
  "subject": "Login issue",
  "body": "Full ticket description...",
  "status": "open",
  "priority": "high",
  "typology": "incident",
  "external_id": "12345",
  "requester": {
    "id": 456,
    "email": "[e-mail]",
    "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:

{
  "status_id": 2
}

Response:

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

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

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

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

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

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:

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

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

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

{
  "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 - Complete ticketing documentation
• Form Configuration - Form field configuration
• Zendesk Integration - Zendesk setup
• HelpScout Integration - HelpScout setup