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: Authenticated user session or the configured tenant API key (X-API-Key). Scoped public API keys do not authenticate this endpoint.

Request: multipart/form-data. Include subject, body, typology and priority. Additional fields include thread_id, ticket_form_id, files, user_email and JSON-encoded metadata. Non-staff users must provide an accessible conversation. A requested form must be available to that user and match the active provider.

Example request:

curl -X POST "https://your-domain.com/api/ticketing/create-ticket" \
  -H "Authorization: Bearer your-session-token" \
  -F "subject=Cannot log in" \
  -F "body=The sign-in page returns an error" \
  -F "typology=Incident" \
  -F "priority=High" \
  -F "thread_id=00000000-0000-4000-8000-000000000001"

Success response (201):

{
  "id": "00000000-0000-4000-8000-000000000002",
  "ticket_url": ""
}

The response confirms ticket creation. If its inline Ago or Zendesk form has automatic internal note instructions, note generation starts separately after creation succeeds. This response does not wait for the note. Opening or prefilling a form never generates a note.

Missing required request fields return 422; malformed JSON in metadata returns 400. Unauthorized form or conversation access returns 403, missing conversations return 404, and disabled conversations return 410 for non-staff users. Errors caught during ticket creation contain error and message strings; request validation errors use a detail list.

---

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