Ticket Endpoint

Example: Create a ticket

POST /Import/JSON/tickets
Authorization: Bearer {token}
Content-Type: application/json
{
  "type": "tickets",
  "data": [{
    "ticket_subject": "API-Test-Ticket",
    "ticket_customers_email": "kunde@example.com",
    "ticket_customers_name": "Max Mustermann",
    "ticket_priority_id": 2,
    "ticket_department_id": 1,
    "ticket_comments": "Erstellt via xoPort API",
    "admin_id": 0,
    "attachments": [
      { "name": "bestellung.pdf", "content_base64": "JVBERi0xLjQKJcfs…" }    ],
    "assigned_admins": [1, 3]
  }]
}

Comment format

"ticket_comments": "Internal note via API",
"admin_id": 1

`ticket_comments ` is the comment text; `admin_id ` is its author (0 = system, >0 = admin ID; this is validated).

Example: Update a ticket with a comment

PUT /Import/JSON/tickets
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "tickets",
  "data": [{
    "ticket_id": 42,
    "ticket_status_id": 3,
    "ticket_priority_id": 1,
    "ticket_comments": "Status auf Erledigt gesetzt",
    "admin_id": 1,
    "assigned_admins": [1, 5]
  }]
}

In the export, each ticket contains a ` linked_appointments[] ` array with linked CRM appointments:

"linked_appointments": [
 {
    "appointment_id": 15,
    "startdate": "2026-04-14 10:00:00",
    "enddate": "2026-04-14 11:00:00",
    "allday": 0,
    "done": 0,
    "status_id": 1,
    "title": "Rückruf Kunde",
    "description": "Bezüglich offener Rückfrage",
    "location": ""
  } 
]

Appointments are linked via ` xocrm_appointments_relationships ` (target_type = ticket_id). Deleting a ticket only removes the link, not the appointment itself.

Fixed in v2.118.1: linked_appointments to POST/PUT /Import/JSON/tickets also triggered the warning " UNKNOWN_FIELD," even though the appointments were created. The warning has been removed; processing remains unchanged.

File attachments are addressed via the ticket ID:

Listing: GET /ticket_attachments/{id}

{
  "success": true,
  "ticket_id": 42,
  "ticket_link_id": "8i1c5O8g7w8b5c",
  "files": [
    {
      "name": "screenshot.png",
      "size": 245760,
      "mime_type": "image/png",
      "last_modified": "2026-03-15 14:30:22"
    }
  ]
}

Download: GET /ticket_attachment/{id}?file=screenshot.png

Binary download with correct Content-Type and Content-Disposition: attachment headers. Path traversal protection via basename() + realpath() validation.

Upload: attachments[] via POST/PUT NEW v2.60.0

Up to v2.59.0, attachments could only be read —they were added exclusively via the backend form. A ticket created via the API would therefore have no supporting documents (PDF, .eml, screenshot). Starting with v2.60.0,POST/PUT /Import/JSON/tickets accepts the optional attachments[] field:

"ticket_comments": "Documentation for the complaint",
"admin_id": 1,
"attachments": [
 {
    "name": "rechnung.pdf",
    "content_base64": "JVBERi0xLjQKJcfs…"
  } 
]

Storage uses the same mechanism as the backend upload—same extension allowlist, __ naming convention, and hash-based deduplication to prevent duplicate storage. The actual file name assigned for each record is listed in the response under `attachments`. The upper limit per file corresponds to the ` /media` endpoint(XOPORT_MEDIA_MAX_FILESIZE, default 10 MB).

Invalid entries (unallowed file extension, invalid Base64, size exceeded) generate an error for each file; the ticket update itself remains successful. If ` is_public_reply: true ` is set along with ` notify_customer: true `, the files are sent with the customer email—they are written before the email is sent.

A claim indicates that someone is currently working on a ticket, for example, an AI agent acting on behalf of an employee. Other agents see this claim in the export and in the backend (ticket list and ticket view) and do not start working on the ticket simultaneously. The claim is a notification, not a lock: it is not enforced by write access checks, and the ticket remains editable for everyone.

PUT /Import/JSON/ticket_claims
{
  "type": "ticket_claims",
  "data": [
    { "ticket_id": 33999, "admin_id": 12, "state": "claimed", "ttl_minutes": 60, "label": "KI-Agent" }
  ]
}

Result per record

records[].status refers to the result; records[].claim refers to the status after the call:

Response (HTTP 200) when another administrator makes a request while Max Mustermann holds the claim:

{
  "success": false,
  "outcome": "failed",
  "api_version": "2.118.1",
  "type": "ticket_claims",
  "stats": { "total": 1, "claimed": 0, "refreshed": 0, "taken_over": 0, "released": 0, "unchanged": 0, "failed": 1 },
  "errors": [
    { "record": 1, "error": "Ticket 33999 is claimed by Max Mustermann (admin_id 12) until 2026-09-17 14:05:10. Send force=true to take it over." }
  ],
  "timestamp": "2026-09-17 13:20:02",
  "records": [
    {
      "index": 1,
      "ticket_id": 33999,
      "status": "conflict",
      "claim": {
        "admin_id": 12,
        "admin_name": "Max Mustermann",
        "label": "KI-Agent",
        "claimed_at": "2026-09-17 13:05:10",
        "expires_at": "2026-09-17 14:05:10",
        "expires_in_seconds": 2708
      }
    }
  ]
}

Automatic Release

• Public response to the customer, via API (PUT /Import/JSON/tickets) or in the backend. It doesn’t matter who responds.
• Change to a “Closed” status. Saving a ticket that is already closed does not release a claim.
• Expiration of the validity period.

An internal note does not release the claim. Setting and releasing do not change ticket_date_last_modified or the history and do not trigger any events; sorting and delta export (?last_modified=) remain unaffected. There is at most one claim per ticket: Of two simultaneous requests, exactly one receives conflict.

Starting with Shop 4.9.73: If the ticket_claims table is still missing, the endpoint responds with an HTTP 503 TICKET_CLAIMS_UNAVAILABLE; the Shop creates it during the next schema synchronization (when opening an xoCRM page or the HealthCheck).