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 Supported and 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.

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.

  • Objects and Fields - object classes, identification, field names, HTML fields, and lookups.