Ticket

All communication within Omnidesk is facilitated through tickets. Tickets can contain messages (displayed on the timeline), have a status (like new, open or solved) and be assigned to groups. These and many other options are available through the API.

get
Get timeline

https://account.omnidesk.com/api/v2/ticket/:ticketID
This method will show the ticket and corresponding timeline, including status, tags, assignment, messages etc.
Request
Response
Request
Path Parameters
optional
string
Response
200: OK
{
"type": "item",
"item": {
"assigned_group_id": 10003,
"assigned_user_id": 0,
"channel_account_id": "0",
"channel_id": 1,
"closed_at": null,
"created_at": "2019-09-28 22:06:16",
"customer_id": 626822,
"direction": "inbound",
"external_gui_url": "https://guiurl.brand.com/?ticketID=858462#20164564646592575",
"external_id": "BFFDAFF1-6E3F-2244-93EE-65A9CF3D0ECE.1",
"form_id": null,
"from": "thomas@test.com",
"from_name": "",
"grade_by_customer": null,
"icon": "e-mail",
"last_update": "2019-09-28 22:06:16",
"last_update_agent": null,
"last_update_customer": "2019-09-28 22:06:16",
"priority": "medium",
"show_timeline": 1,
"sla_breach_customer_wait_time": null,
"sla_breach_first_reply_time": "2019-10-01 12:00:00",
"sla_breach_next_reply_time": null,
"sla_breach_user_work_time": null,
"sla_next_breach": "2019-10-01 12:00:00",
"sla_next_breach_current_status": "active",
"sla_policy_id": 5,
"snooze_time": null,
"snooze_time_sent": null,
"title": "vraag van Thomas",
"to": "service@mybrand.com",
"to_name": "",
"status": "new",
"id": 858462,
"channel_name": "e-mail",
"channel_icon": "e-mail",
"brand_name": "MyBrand",
"brand_id": 2,
"timeline": [
{
"id": 4090647,
"ticket_id": 858462,
"item_type": "assigned_group_id",
"item_type_id": "10003",
"description": "Assigned to Servicee",
"initiated_by": "trigger: Assign to service",
"created_at": "2019-09-28 22:06:23",
"type": "event"
},
{
"to": null,
"from": null,
"image": "",
"created_at": "2019-09-28 23:30:13",
"pinned": 0,
"id": "3143281",
"channel_name": null,
"channel_icon": null,
"type": "note",
"status_new": "open",
"user_id": 254,
"user_name": "marleen",
"user_avatar": "",
"channel_id": 0,
"direction": "",
"content": "My intern note on this ticket",
"ticket_id": 858462,
"external_id": null,
"from_name": "",
"to_name": "",
"meta_data": "[]",
"in_queue": 0,
"send_at": null,
"files": []
},
{
"to": "service@mybrand.com",
"from": "thomas@test.com",
"image": "",
"created_at": "2019-09-28 22:06:17",
"pinned": 0,
"id": "3143690",
"channel_name": "e-mail",
"channel_icon": "e-mail",
"type": "message",
"status_new": "new",
"user_id": 0,
"user_name": "Anonymous",
"user_avatar": "",
"channel_id": 1,
"direction": "inbound",
"content": "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.0 Transitional//EN\" \"http://www.w3.org/TR/REC-html40/loose.dtd\">\n<html><body><p><b>HTML</b> email content</p></body></html>\n",
"ticket_id": 858462,
"external_id": "BFFDAFF1-6E3F-2244-93EE-65A9CF3D0ECE.1",
"from_name": "",
"to_name": "",
"meta_data": "{\"to\":[{\"address\":\"service@mybrand.com\",\"name\":\"\"}]}",
"in_queue": 0,
"send_at": null,
"content_whole": "<b>HTML</b> content",
"email_details": "to: service@mybrand.com",
"email_show_reply_all": false,
"files": []
}
],
"following": false,
"sla_next_breach_seconds": 222706,
"customer": {
"id": 626822,
"brand_id": 2,
"external_primary_id": "20164564646592575",
"firstname": "T",
"lastname": "van Test",
"created_at": "2019-09-28 22:06:16"
},
"customer_channels": [
{
"id": 1194929,
"brand_id": 2,
"customer_id": 624822,
"channel_id": 1,
"unique_reference": "thomas@test.com",
"linked_by_user_id": 0,
"name": "e-mail",
"icon": "e-mail"
},
{
"id": 1194930,
"brand_id": 2,
"customer_id": 626822,
"channel_id": 2,
"unique_reference": "+3164568456",
"linked_by_user_id": 0,
"name": "telephone",
"icon": "telephone"
}
],
"tags": "",
"customer_custom_fields": [],
"assign_options_groups": [
{
"id": 10002,
"name": "Finance"
},
{
"id": 10003,
"name": "Customer Support"
}
],
"assign_options_users": [
{
"id": 1,
"name": "thomas"
},
{
"id": 2,
"name": "marleen"
}
],
"original_channel_id": 0
}
}

post
Create a ticket

https://account.omnidesk.io/api/v2/ticket
Please note that the to and from should be inverted when using direction outbound.
Request
Response
Request
Body Parameters
assignedGroupID
optional
integer
id of the group assigned to the ticket
to
required
string
to address, for instance helpdesk@brand.com
from
required
string
from address, for instance customer@freemail.com
direction
required
string
inbound or outbound
channelID
required
integer
see our channelID documentation, 1 = email
brandID
required
integer
brandID can be viewed in settings > brands
title
required
string
title of the ticket
formID
optional
integer
form id you want to attach to the ticket
Response
200: OK
{"type":"item","item":{"id":"", "other ticket fields": ...}}

After that you can start adding information to the ticket. As an example we will set the status of the ticket below or add a message or update form fields (see the subpages: message, form field, etc).

put
Update Ticket

https://account.omnidesk.io/api/v2/ticket/:ticketID
Provide the fields you want to update. All fields are optional. If you do not provide a certain field it will not get updated.
Request
Response
Request
Body Parameters
title
optional
string
status
optional
string
Status changes of a ticket will trigger updated trigger
externalPrimaryID
optional
string
Your primary (customer) ID, if the customer does not exist the ticket will be set to no customer.
Response
200: OK
{"type": "result", "message": "Ticket updated."}

post
Set the status of a ticket

https://account.omnidesk.io/api/v2/ticket/setstatus
Status updates will trigger the updated trigger.
Request
Response
Request
Body Parameters
ticketIDs[]
required
integer
List of ticket ids the change should be applied to.
status
required
string
Options: new, open, pending, holding, solved, closed
Response
200: OK
{ "type": "result", "message": "Ticket status is updated."}