List of tickets

General points

POST https://secure.usedesk.com/uapi/tickets

Warning. If you use the server version of Usedesk, you will have a different URL of methods. Check the URL for the API with our team — support@usedesk.com.

The method returns a list of company tickets. Filters can be used.

* — mandatory parameters

Parameters of query

Parameter	Value
api_token*	API channel token
fchannel	Filter by channel id. Pass multiple values separated by commas
fassigned	Filtering by assignee_id and group_id, whose values can be passed as an array or one at a time. There are the following cases of behavior: You can specify an agent's id in the assignee_id parameter and a group id in the group_id parameter — then the system sends all tickets where an agent is specified as an Assignee within a certain group You can to not specify the group_id parameter and specify agent's id in the assignee_id parameter — then the system sends all tickets where an agent is specified as the Assignee, without taking into account which group it is added to You can specify the parameter assignee_id = unassigned — then the system sends all tickets in which a group is specified as the Assignee You can specify parameter assignee_id = unassigned and specify in parameter group_id = unassigned — then the system sends all tickets where "No Assignee" is specified as the Assignee Deprecated (version 1.0). We do not recommend using deprecated parameters: Ability to specify agent id as a string Ability to specify group id+agent id to specify within which group the actor is specified: {Group id}_{agent id}
fgroup	Filter by group id Pass multiple values separated by commas
fstatus	Filtering by status id 1 (open) 2 (executed) 3 (closed) 4 (deleted) 5 (on hold) 6 (pending) 7 (spam) 8 (new) 9 (mailing) Pass multiple values separated by commas
ftype	Filtering by type question task problem incident Pass multiple values separated by commas
fpriority	Filtering by priority low medium urgent extreme Pass multiple values separated by commas
accessible_for_agent_id	Filtering by agent id, takes into consideration employee's rights. The server returns the variable rights: write — if there is access to work with the ticket in the current channel; read — if there is access to view the ticket in the current channel does not accept "null"
offset	Offset. Offset by 1 will show the next 100 entries does not accept "null"
tag	Filtering by tag value. If there is more than one value, pass the values with a comma and a space: "tag" : "1,4,23" does not accept "null"
created_after	Tickets created after the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' Important! Our API works according to the zero time zone (UTC+0) and doesn't depend on the company's working hours. Keep this in mind when creating a filter.
created_before	Tickets created before the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' Important! Our API works according to the zero time zone (UTC+0) and doesn't depend on the company's working hours. Keep this in mind when creating a filter.
updated_after	Tickets that were changed after the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' Important! Our API works according to the zero time zone (UTC+0) and doesn't depend on the company's working hours. Keep this in mind when creating a filter.
updated_before	Tickets that were changed before the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' Important! Our API works according to the zero time zone (UTC+0) and doesn't depend on the company's working hours. Keep this in mind when creating a filter.
query	String to search. The search will be made by the subject of the query and the content in all comments. A limit of 10 queries per minute is set for queries, containing this parameter. does not accept "null"
client_id	Client Id If you specify value, the system will send a list of tickets for a particular client
fields	Filtering by ID and value of additional field. The array contains parameters: id — ID of additional field; value — value of additional field. а) empty — If this value is specified, the system will filter out all queries with at least one unfilled field. For fields with the "unfilled" checkbox type this value is 0 or empty " ". b) not_empty — If this value is specified, the system will filter out all tickets with at least one filled field. For fields with checkbox type "filled" this value is 1. c) value — if you specify a value, the system will filter out all tickets, in which that value is selected in any of the additional fields. You can specify only one value Deprecated (version 1.0). We do not recommend using deprecated parameters field_id – filtering by optional field identifier. If you specify a value, the system will filter all tickets in which this field will be filled. You can specify only one value. field_value – filtering by value of additional field. empty — if this value is specified, the system will filter out all queries that have at least one empty field For fields with the checkbox type "not filled" this value is false not_empty — if this value is specified, the system will filter out all tickets that have at least one filled field. For fields with the checkbox type "filled" this value is true value — if this value is specified, the system will filter out all tickets with this value in any of the additional fields. Only one value can be specified
sort	Sorting parameter, by which you can sort the ticket list: id, status_id, client_id, assignee_id, group, last_updated_at, published_at By default: id
order	Sort order of tickets: asc — ascending desc — descending By default: desc
properties	Returns in response from the server the date and time of SLA for each parameter, if they are specified in the tickets: first reply time (first_reply) next reply time (next_reply) resolution time (close)

Examples of using parameters in a query

An example of applying filtering

{
    'fchannel':'123',
    'properties': ["sla"]
    'fassigned': 
    [
       {
            'assignee_id' : 17063,
            'group_id' : 6216
       },
       {
            'assignee_id' : 15023,
            'group_id' : 8294
       } 
    ]
    'fields': 
    [
        {'id': 4704,
         'value": 1
        },
        {'id': 2410,
         'value": 'empty'
        },
        {'id': 3570,
         'value": 'test'
        },
        {'id': 4267,
         'value': 'empty'
        }
    ]
    'fgroup': '21',
    'ftype':'1',
    'accessible_for_agent_id':'6339',
    'updated_after':'2016-11-25 00:00'
}

Sample request in php

$data = array(
        'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
        'offset'=>0,
        'created_after' =>'2016-11-25 00:00',
        'created_before'=>'2016-11-25 15:08',
);
$mch_api = curl_init(); // initialize cURL connection
curl_setopt($mch_api, CURLOPT_URL, 'https://secure.usedesk.com/uapi/tickets');
curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
curl_setopt($mch_api, CURLOPT_POST, true);
curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($mch_api); 
return $result;

Sample request with filters in php

$data = array(
        'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
        'offset'=>0
        'tags'=> 'tag1,tag2',
        'fchannel'=>'123',
        'fgroup'=>'2'
);
$mch_api = curl_init();
curl_setopt($mch_api, CURLOPT_URL, 'https://secure.usedesk.com/uapi/tickets');
curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
curl_setopt($mch_api, CURLOPT_POST, true);
curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($mch_api);
return $result;

An example of a server response

[
    {
        "id": 2992803,
        "subject": "Hi there!",
        "client_id": 15341,
        "client_name": "John Jones",
        "assignee_id": 2,
        "channel_id": null,
        "group": 2,
        "created_at": "2019-05-16 11:31:23"
        "last_updated_at": "2017-03-29 07:47:30",
        "channel_email": null,
        "active_sla": [
            {
            "type": "close",
            "date": "2021-04-29 10:35:04"
            },
            {
            "type": "first_reply",
            "date": "2021-04-28 18:01:08"
            }
        ],
            "ticket_fields": [
            {
                "id": 25,
                "name": "Complain",
                "value": null
            },
              {
                "id": 37,
                "name": "Reason",
                "value": "39"
            }
        ],
        "tags": [
            {
                "name": "Imortant"
            },
            {
                "name": "Cold"
            }
        ],
        "status": 2,
        "priority": "medium",
        "type": "question",
        "last_comment": "I have a problem",
        "remind_at": null,
        "rights": "read"
    },
]

Parameters of the query responses

Parameter	Value
id	Ticket ID
subject	Subject of ticket
client_id	Client ID
client_name	Name of a client
assignee_id	ID of ticket's assigned user
channel_id	Channel ID
group	IG of assigned group
created_at	Date and time of ticket creation Time Zone — UTC+0
last_updated_at	Date and time of the last ticket update Time Zone — UTC+0
channel_email	Email of the channel Only for the corresponding channel type
active_sla	Array of current ticket's SLA type: close — SLA for resolution; first_reply — SLA for first reply; date — date and time of SLA expiration.
ticket_fields	Array with values of additional fields in the query id — ID of additional field; name — name of additional field; value — value of additional field.
tags	Array of tags name — tag name.
status	Ticket status
priority	Ticket priority
type	Type of ticket
last_comment	Last comment in the ticket
remind_at	Reminder date and time Time Zone — UTC+0
rights	Rights of the specified employee write — if there is access to work with the ticket in the current channel; read — if there is access to view the ticket in the current channel.

Categories

List of tickets

General points

Parameters of query

Examples of using parameters in a query

Parameters of the query responses

Was the article helpful?

Thanks for the feedback!

Advise how to improve the article

Thanks for the feedback!