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 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: 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 requests 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 requests 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 requests 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 requests 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 request in the current channel; read — if there is access to view the request 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	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: 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 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. 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 requests 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 requests 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 requests: 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 requests: 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 request in the current channel; read — if there is access to view the request 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!