List of tickets
General points
POST https://api.usedesk.ru/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 requests. 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:
Deprecated (version 1.0). We do not recommend using deprecated parameters:
|
fgroup | Filter by group id Pass multiple values separated by commas |
fstatus |
Filtering by status id
Pass multiple values separated by commas |
ftype |
Filtering by type
Pass multiple values separated by commas |
fpriority |
Filtering by priority
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:
does not accept "null" |
offset | Offset.
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 | Requests created after the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' |
created_before | Requests created before the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' |
updated_after | Requests that were changed after the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' |
updated_before | Requests that were changed before the date in the parameter (inclusive) will be shown in the response. Example: '2016-11-25 00:00' |
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 requests for a particular client |
fields |
Filtering by ID and value of additional field. The array contains parameters:
а) 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 requests 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 requests, 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 requests in which this field will be filled. You can specify only one value. field_value – filtering by value of additional field.
|
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 requests:
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 requests:
|
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://api.usedesk.ru/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://api.usedesk.ru/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
|
ticket_fields |
Array with values of additional fields in the query
|
tags |
Array of tags
|
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
|