Ticket Reference Lists

9 Aufrufe Markdown

Four lists that supply the values a ticket write accepts, and one figures endpoint.

Overview

None of these five endpoints writes anything; they tell you which values are valid when you do. The department, staff, priority and status lists are where the values accepted by the ticket write endpoints come from.

Four of them vary by installation. There are as many departments as an operator set up. Priority labels come from a language file, and an installation can add statuses of its own. So do not write any of them into your code: the list will not hold on another installation.

The fifth is a summary for the period you pick. It covers how many tickets are open and solved, how long answers and solutions take, and what clients scored.

Reference

Listing the Departments

get/api/v1/admin/tickets/departments

Tickets/GetTicketDepartments admin

Returns the departments a ticket can go to.

Response fields data[] — 5

idintThe department id. This is what a ticket write takes.

namestringThe department name.

descriptionstringWhat it is for.

iconstringIts icon.

icon_typestringWhat kind of icon it is.

Errors 1

insufficient_scope403The key lacks the required scope.

Request

curl 'https://panel.example.com/api/v1/admin/tickets/departments' \
  -H "Authorization: Bearer $API_KEY"

const res  = await fetch('https://panel.example.com/api/v1/admin/tickets/departments', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();

$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/departments');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// The names arrive in the INSTALLATION's language; do not expect them translated for you.
$departments = Api::Tickets()->GetTicketDepartments()['data'];

Listing the Staff You Can Assign

get/api/v1/admin/tickets/assignable-staff

Tickets/GetTicketAssignableStaff admin

Returns the staff a ticket can be assigned to.

Response fields data[] — 3

idintThe staff id. This is what an assignment takes.

full_namestringTheir name.

emailstringTheir e-mail address.

Errors 1

insufficient_scope403The key lacks the required scope.

Request

curl 'https://panel.example.com/api/v1/admin/tickets/assignable-staff' \
  -H "Authorization: Bearer $API_KEY"

const res  = await fetch('https://panel.example.com/api/v1/admin/tickets/assignable-staff', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();

$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/assignable-staff');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// This is NOT every administrator: only people named as handlers on a department come back.
$staff = Api::Tickets()->GetTicketAssignableStaff()['data'];

Listing the Priorities

get/api/v1/admin/tickets/priorities

Tickets/GetTicketPriorities admin

Returns the priorities a ticket can carry.

Response fields data[] — 2

valueintThe priority value. This is the number a ticket write takes.

labelstringWhat it is called.

Errors 1

insufficient_scope403The key lacks the required scope.

Request

curl 'https://panel.example.com/api/v1/admin/tickets/priorities' \
  -H "Authorization: Bearer $API_KEY"

const res  = await fetch('https://panel.example.com/api/v1/admin/tickets/priorities', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();

$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/priorities');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// The label comes from a language file; hard-code the numbers rather than the NAMES.
$priorities = Api::Tickets()->GetTicketPriorities()['data'];

Listing the Statuses

get/api/v1/admin/tickets/statuses

Tickets/GetTicketStatuses admin

Returns the standard statuses together with the installation's own.

Response fields data[] — 8

keystringThe status key. A plain word for a standard one, and the base joined to an id for a custom one.

namestringThe name it shows under.

typestringWhether it is standard or custom.

badgestringThe badge class. Standard statuses only.

iconstringIts icon. Standard statuses only.

idintThe custom status id. Custom statuses only.

basestringThe standard status it sits on. Custom statuses only.

colorstringIts colour. Custom statuses only.

Errors 1

insufficient_scope403The key lacks the required scope.

Request

curl 'https://panel.example.com/api/v1/admin/tickets/statuses' \
  -H "Authorization: Bearer $API_KEY"

const res  = await fetch('https://panel.example.com/api/v1/admin/tickets/statuses', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();

const standard = data.filter((s) => s.type === 'standard');

$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/statuses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// They go to two different fields: the standard one to the status, the custom one to its own.
$all    = Api::Tickets()->GetTicketStatuses()['data'];
$custom = array_filter($all, fn ($s) => $s['type'] === 'custom');

Reading the Figures

get/api/v1/admin/tickets/stats

Tickets/GetTicketStats admin

Returns support counts and speed figures for the period you pick.

Query 1

periodstringWhich period: today, yesterday, this_week, last_week, this_month, last_month, last_3_months, last_6_months, this_year, last_year, all_time. All time by default.

Response fields data — 10 + meta

openintHow many are open.

pendingintHow many wait on the client.

answeredintHow many have been answered.

resolvedintHow many are solved.

totalintHow many there were in the period.

avg_responsestringThe average time to answer. Readable text rather than a number.

avg_resolutionstringThe average time to solve. Readable text as well.

resolution_ratenumberThe share that got solved.

avg_ratingnumber | nullThe average satisfaction score. Empty when nobody scored.

rating_countintHow many scores were given.

periodstringThe period the figures cover. It comes back under meta.

Errors 1

insufficient_scope403The key lacks the required scope.

Request

curl 'https://panel.example.com/api/v1/admin/tickets/stats?period=this_month' \
  -H "Authorization: Bearer $API_KEY"

const url = new URL('https://panel.example.com/api/v1/admin/tickets/stats');
url.searchParams.set('period', 'this_month');

const res  = await fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();

$ch = curl_init('https://panel.example.com/api/v1/admin/tickets/stats?' . http_build_query(['period' => 'this_month']));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

// The time fields are READABLE TEXT ('2h 5m'); parse them yourself before charting.
$s = Api::Tickets()->GetTicketStats([], ['period' => 'this_month'])['data'];
$rate = $s['resolution_rate'];

Pitfalls

Assignable staff is not every administrator

This list returns only the people named as handlers on a department. Not every administrator who can sign in appears here. Take an id from your own administrator list and the assignment fails as an invalid staff member. Pick the value from here instead.

The status list feeds two different fields

The list returns standard statuses and the installation's own together, yet the two go to different fields. The standard one goes to the status, and the custom one by its id to the custom status field. Putting a custom key into the status field gives an invalid status error.

The time fields are text, not numbers

The average answer and solve times arrive as readable text, so you cannot chart or add them as they come. Parse them yourself when you need a number. In the same summary the solve share and the score count are real numbers and go straight into a calculation.

The labels come in the installation's language

Department names, priority labels and status names arrive in the installation's current language; they are text to show rather than an identity. Base decisions on the numeric values and keys instead of the names, or your logic quietly slips the day the language changes.

An empty period comes back as zeros

For a period with no tickets the counts come back as zero, the times as zero minutes and the average score empty. Those are not signs of success: a zero solve time does not mean you were fast, it means there was no work. Check the total before you put any of it on a dashboard.

War das hilfreich?

Vielen Dank für Ihre Rückmeldung!

Brauchen Sie weitere Hilfe?

Unser Support-Team ist rund um die Uhr für Sie da, wenn Sie oben nicht fündig werden.

Kontakt aufnehmen Ticket eröffnen

Overview

Reference

Listing the Departments

Listing the Staff You Can Assign

Listing the Priorities

Listing the Statuses

Reading the Figures

Pitfalls

Related Articles