Ticket API for apps

Your ERP (or any other app) can open support tickets for its users, add their follow-ups, and show the support team’s replies. Everything is scoped to the app that owns the key: an app never sees another app’s tickets.

Keys

Inbox → Settings → Apps & API keys → Create API key. The key (odk_…) is shown once. Send it from your server only:

Authorization: Bearer odk_...

Revoking a key stops it on the next request. To rotate, create a second key for the same app, deploy it, then revoke the old one.

Check a key:

curl -s https://desk.example.com/api/v1/me -H "Authorization: Bearer $KEY"

Endpoints

Method	Path	Body / query	Returns
POST	`/api/v1/tickets`	`{"customer": {"id", "name", "email", "phone"}, "subject", "body", "priority", "tags": []}`	201, the ticket. Always a new ticket.
GET	`/api/v1/tickets`	`?customer_id=<your user id>`	`{"items": [ticket]}`, newest first (50)
GET	`/api/v1/tickets/{ticket_no}`		`{"ticket", "messages": [...]}`, oldest first (newest 200); internal notes are never included
POST	`/api/v1/tickets/{ticket_no}/messages`	`{"body"}`	201, the message. 409 if the ticket is closed: open a new one.

customer.id is your app’s own user id (required, up to 128 characters). Name, email and phone fill in the customer’s profile for agents.
subject: 1–200 characters. body: 1–10,000 characters.
priority: low, normal (default), high or urgent. tags: up to 20, each 1–32 of a-z 0-9 - _ (lowercased for you), e.g. ["payroll", "erp"].
In a ticket’s messages, direction is in for the customer and out for support replies; sender_type is contact or agent.
Ticket status: new, open, waiting_customer, resolved, closed. A message on a resolved ticket reopens it.

Errors are {"error": {"code", "message"}}: 401 bad or revoked key, 404 unknown ticket (or another app’s), 409 closed ticket, 422 invalid input.

Example

curl -s https://desk.example.com/api/v1/tickets -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
  "customer": {"id": "u-9", "name": "Karim", "email": "karim@example.com"},
  "subject": "Cannot export payroll",
  "body": "Export fails with error 500 since this morning.",
  "priority": "high",
  "tags": ["payroll"]
}'

There are no webhooks yet: poll GET /api/v1/tickets/{ticket_no} (for example when the user opens the ticket page) to show new replies.