List and Read Objects
On this page
Read routes return the response envelope.
Check success to determine whether a request succeeded: once a read route
runs, it returns HTTP status 200 even on failure. Authentication and
request checks can reject a call before it reaches the route.
On a list route, responseObject is a Fields / Data pair rather than an
array of objects. In a JSON response, each Fields entry carries Name,
DataType, and Caption; each row in Data lists its values in the same
order, so you match a value to its field by position. Every value comes back as a plain
string, whatever the column's type; to interpret it, read the matching
field's DataType. DataType is always one of fourteen values: string,
memo, int, bool, money, float, date, datetime, guid,
image, duration, encrypted, html, or array.
Which classes you can address, how a record is identified, how field names
and HTML fields work, and how to read the values behind a lookup field
(classification values) through /Dictionary are covered in
Objects and Fields.
Before you begin
- Every request to these routes must use HTTPS. A plain-HTTP request is refused with
505 HTTP Version Not Supportedand the message "HTTP protocol is not supported." - Each request carries a bearer token, or the caller's Windows credentials when the instance uses Windows authentication.
What you can see
In a technician account's own session, the rows these routes return are filtered exactly as in the account's Web App session, by its security roles.
In an impersonated session, listing a class that is not a Self Service Portal class is refused with "You do not have enough permissions to access this item.", reading an object of such a class is refused as well, and the rows of a Self Service Portal class are limited by the portal's own row and ticket access-level filters.
In the API
List objects
GET or POST /{objectClass} returns the rows of that class's list view.
Besides the ordinary classes, four aggregate views can be listed this way:
All CIs, All Tickets, My Tickets, and Task Parents; see
Objects and Fields for the names each answers to. My
Tickets returns the tickets assigned to the person whose login the session
runs under, or to a group that person belongs to. For a password-grant token
that is the technician the token was issued to; otherwise it is the API
service session. My Tickets leaves out every ticket in the Closed status of
its ticket class: Incident, Problem, Change Request, Service Request, or Work
Order. Task Parents combines projects and tasks.
The GET and POST forms of a list request are not equivalent:
| GET | POST (JSON body) | |
|---|---|---|
| Fields to return | par_fields (comma-separated) |
fields |
| Sort | par_sort_asc, par_sort_desc (comma-separated) |
sort, entries with property and direction |
| Paging | par_offset, par_limit |
offset, limit |
| Full-text search | par_search_text |
searchText |
| View name | par_view_name |
viewName |
| Filters | every other query parameter, as an equality filter on the field of that name | filters, entries with name, value, and operation |
On GET, the parameter names are matched exactly, including case:
PAR_FIELDS is not the field list but an equality filter on a field of
that name. Nine names are reserved on every route: the seven in the table,
plus par_objectClass and par_refField, the /Dictionary parameters
described in Objects and Fields. None of the nine can name a
field filter.
Query parameter values are decoded before they are used, so
Assignee=John%20Doe filters on John Doe. Percent-encode spaces, &,
=, #, +, and % in a value; an unencoded + is read as a space. In
par_fields, par_sort_asc, and par_sort_desc, both a literal comma and
an encoded %2C separate names, each name is trimmed, and empty names are
dropped. Because a comma always separates names, a name that contains a
comma cannot be listed.
Filters
Only the POST form can filter on anything but equality. The accepted
operations are =, <>, <, >, <=, and >=, spelled exactly so; any
other value is rejected with "An invalid value was specified for query
parameter 'operation'."
A filter value for a GUID, integer, or boolean column that does not parse
is rejected with a message naming the expected type. A date filter given as
yyyy, yyyy-mm, yyyy-mm-dd, or the compact form of one of those covers
that whole period: = means within that year, month, or day, and > means
after the end of it. A longer value is read as a full ISO timestamp.
Search
par_search_text on GET and searchText on POST run an all-words
full-text search over the class's frequently used text fields, combined
with the request's other filters: a row must match every word. A span in
double quotes counts as one phrase.
View name
On a class list, par_view_name on GET and viewName on POST have an
effect only when you list Approval Requests with the value
PendingApprovals: the list then adds a pending-approvals filter. With any
other value, or on any other class, the list queries the class's normal list
view with the same default fields and sort order. The view name does not
select a saved view, and a name that matches no view causes no error.
Field names
When a class list request names no fields (no par_fields on GET, no
fields in a POST body), each row carries every field of the class's list
view, in the order the product lists them, except the fields the product's
built-in exclusion rules leave out, among them the currency code when
multiple currencies are not licensed.
A name in the field list, a filter, or a sort must match a field's name
exactly, including case; a field's caption, default label, or custom label
does not match. An unknown name fails the whole request with
"Field '<name>' is unknown." Under version v2, a name that is the
plain-text half of an HTML field pair is answered with the HTML half
instead.
Sorting and paging
When you give no sort, the list uses its default order: Ticket for a
ticket class, My Tickets, and the general Ticket object; OID for other
workflow objects, Approval Requests, and All CIs; PO_Number, Line
for Purchase Order Items; ID, Name for Stock Rooms; ID,
Product_Name for Software Products; and ID otherwise. These fields set
only the order of the rows; they do not limit which fields are returned.
In the POST form, a sort entry whose direction is desc sorts that
field the same way as naming it in par_sort_desc.
With a positive limit, the rows are paged in the sort order you give or,
when you give none, in the list's default order. When a GET request has no
par_limit or a POST body omits limit, the limit is the largest integer,
so an unparameterized request returns every row you may see. An offset a
POST body omits is 0; an unparsable par_offset falls back to 0, and an
unparsable par_limit to the largest integer. A limit of 0 or less
turns paging off rather than asking for no rows: the offset is ignored and all rows are returned, still in the
sort order when one applies. A POST with no body at all is treated the same
way.
Rights and unknown classes
A class name that matches no addressable class is refused with "requested
object is of unknown class". If a technician account's roles give it no
view right on the class, the list still answers successfully with an empty Data; nothing in
the response tells "no rights" apart from "no matching rows".
Read one object
GET /Object/{objectId} returns one object as a list of entries. In a JSON
response, each entry has the lower-case keys name, caption, and value;
in an XML response (the request's Accept header asks for XML) the list is
<Items> of <Item> elements. GET /Profile returns the calling
account's own Person record in the same shape. The object id is the
record's GUID or its human-readable identifier; see
Objects and Fields for how it is resolved and for the classes
that are read differently.
The object's entries are every field of the class's list view except
fields excluded by field customization, fields excluded or unlicensed on
the underlying table, the plain-text half of an HTML field pair, and every
identifier-type column other than the object's own ID. Tag columns are
expanded to tag names. Under version v1, an HTML value is converted to
plain text.
Unlike the class list, reading an object fails rather than answering an empty result: a missing object fails with "Object not found.", and an object you have no view rights on fails with "You do not have enough permissions to access this item."
Read an object's activities
GET or POST /Activities/{objectId} returns the object's activity rows,
ordered by activity number (Num) by default. In both its GET and its POST
form, it accepts the same fields, filters, sort, paging, search text, and
view name as a class list, and the same paging rules apply. The search text
and the view name are accepted but have no effect: they neither filter the
rows nor change the fields or the order, and they cause no error.
The fields you can name are the Activity record's own sixteen columns,
ID, Num, Created_by_ID, Created_by, Created_Date, Time_Spent,
Details, Details_HTML, Published, Object_ID, Old_Status,
New_Status, Activity, Category_ID, WF_Item_Num, and
WF_Action_Num, plus five the list adds: Attachments, Category,
Read_Only, Details_Is_Empty, and Pinned. Activity and Details are
separate fields, so to get both, name both. Under version v2, a request
for Details is answered with the Details_HTML column under that name;
under v1, it returns the plain-text Details.
The activity list first checks the object and fails rather than answering an empty list: a missing object fails with "Object not found.", and an object you have no view rights on fails with "You do not have enough permissions to access this item."
Activities are read-only through the API: no route creates one. New
activity content is submitted as part of running a workflow action, with
each activity field named with the Activity. prefix, for example
Activity.Time_Spent.
Read a ticket's collaborators
GET or POST /Collaborators/{objectId} returns the ticket's collaborators,
one person per row, ordered by Full_Name by default. In both its GET and
its POST form, it accepts the same fields, filters, sort, paging, search
text, and view name as a class list, and the same paging rules apply. As on
the activity list, the search text and the view name are accepted but have
no effect.
When the request names no fields, each row carries every person field that
is not excluded. Full_Name alone serves as the field list only when no
column is defined for the collaborator list.
Related topics
- Objects and Fields - object classes, identification, field names, HTML fields, and lookups.