# 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 timeline

<mark style="color:blue;">`GET`</mark> `https://account.omnidesk.com/api/v2/ticket/:ticketID`

This method will show the ticket and corresponding timeline, including status, tags, assignment, messages etc.

#### Path Parameters

| Name             | Type    | Description                              |
| ---------------- | ------- | ---------------------------------------- |
| getTicketHistory | boolean | Also get the event history on the ticket |

{% tabs %}
{% tab title="200 " %}

```
{
    "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
    }
}
```

{% endtab %}
{% endtabs %}

## Create a ticket

<mark style="color:green;">`POST`</mark> `https://account.omnidesk.com/api/v2/ticket`

Please note that the to and from should be inverted when using direction outbound.

#### Request Body

| Name            | Type    | Description                                        |
| --------------- | ------- | -------------------------------------------------- |
| assignedGroupID | integer | id of the group assigned to the ticket             |
| to              | string  | to address, for instance <helpdesk@brand.com>      |
| from            | string  | from address, for instance <customer@freemail.com> |
| direction       | string  | inbound or outbound                                |
| channelID       | integer | see our channelID documentation, 1 = email         |
| brandID         | integer | brandID can be viewed in settings > brands         |
| title           | string  | title of the ticket                                |
| formID          | integer | form id you want to attach to the ticket           |

{% tabs %}
{% tab title="200 " %}

```
{"type":"item","item":{"id":"", "other ticket fields": ...}}
```

{% endtab %}
{% endtabs %}

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

## Update Ticket

<mark style="color:orange;">`PUT`</mark> `https://account.omnidesk.com/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 Body

| Name              | Type   | Description                                                                                       |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------- |
| title             | string |                                                                                                   |
| status            | string | Status changes of a ticket will trigger updated trigger                                           |
| externalPrimaryID | string | Your primary (customer) ID, if the customer does not exist the ticket will be set to no customer. |

{% tabs %}
{% tab title="200 " %}

```
{"type": "result", "message": "Ticket updated."}
```

{% endtab %}
{% endtabs %}

## Set the status of a ticket

<mark style="color:green;">`POST`</mark> `https://account.omnidesk.com/api/v2/ticket/setstatus`

Status updates will trigger the updated trigger.

#### Request Body

| Name         | Type    | Description                                           |
| ------------ | ------- | ----------------------------------------------------- |
| ticketIDs\[] | integer | List of ticket ids the change should be applied to.   |
| status       | string  | Options:  new, open, pending, holding, solved, closed |

{% tabs %}
{% tab title="200 " %}

```
{    "type": "result",    "message": "Ticket status is updated."}
```

{% endtab %}
{% endtabs %}