Objects and Fields

On this page

Supported classes

The class name in a route is matched, without regard to case, against each visible object class's list name, that list name with the spaces removed, or its table name. The object-activity pseudo-class is never addressable. Any other name is refused with "requested object is of unknown class".

The set of classes is fixed in the product. Customization adds fields and lookups to a class, never a new class.

These classes are backed by a table and answer to the table name shown:

Class Table name
Incident Incidents
Problem Problems
Change Request Change_Requests
Approval Stage Approval_Stages
Approval Request Approval_Requests
Work Order Work_Orders
Knowledge Base Article KB_Articles
Project Projects
SLA SLA
Service Services
Asset Assets
Computer Computers
Hardware Hardware
Tracked Software Tracked_Software
Software License Software_Licenses
Software Product Soft_Products
Network Networks
Document Documents
Purchase Order PO
Purchase Order Item PO_Items
Contract Contracts
Configuration Configurations
Library Item Library
Group User_Groups
Location Locations
Organization Organizational_Units
Person Persons
Announcement Announcements
Reservation Reservations
Vendor Vendors
Product Products
Vendor Product Vendor_Products
Stock Room Stock_Rooms
Stock Rule Stock_Rules
Service Catalog Item Service_Catalog_Items
Service Request Service_Requests
Project Task Tasks
Invoice Invoices
Invoice Item Invoice_Items
Consumable Consumables
Brand Brands
Company Address Address

The registered classes Report, My Tasks, My Followed Items, and Starred are not addressable.

Four addressable classes are aggregate views rather than tables:

Class (list name) Also addressable as
All CIs AllCIs, CI_List
All Tickets AllTickets, Ticket_List
My Tickets MyTickets, My_Requests
Task Parents TaskParents, Task_Parent_List

The list names of these four are translated on a translated server, so such a server matches the translated list name.

Task Parents combines projects and tasks in five columns: ID, OID, Status_ID, Type_ID, and one that holds the project's name or the task's summary. All Tickets combines the five ticket classes: Incident, Problem, Change Request, Service Request, and Work Order. My Tickets answers the tickets assigned to the session's person or to a group that person belongs to, except tickets in the Closed status of their class: Incident, Problem, Change Request, Service Request, or Work Order. A ticket with no status is included. A ticket that waits for the person's approval is included only when it is also assigned to that person or one of their groups. Which rows My Tickets answers follows the session's login: the technician's for a token obtained with the technician's password, and the API service session otherwise.

Identification

Where a route takes an object ID, you can pass the record's human-readable identifier (its OID, or the ticket number for a ticket) or its GUID. A value that parses as a GUID is treated as the GUID, anything else as the identifier.

Reading an object by ID, its activity list, and every attachment route find the object through the product's object index. An object that is missing there fails with "Object not found."; the API then checks the caller's view rights before returning anything, and a caller who may not view the object gets "You do not have enough permissions to access this item." A record whose class is not one of the visible classes fails that check with "requested object is of unknown class". Some classes are indexed differently:

Class How to reach a record
Software Products Not in the object index: only through the class list, filtered on ID.
Stock Rooms Not in the object index: only through the class list, filtered on ID.
Vendor Products In the object index with no OID: by GUID only.
Purchase Order Items The OID is the order's OID, #, and the line number.

Running an action against an object, or checking whether the action is available, does not use the object index; it looks in the action's own object table. There, an identifier that is not a GUID is the ticket number for the general Ticket object and for Change Requests, Incidents, Problems, Service Requests, and Work Orders, and the OID for every other workflow object. Stock Rooms and Invoice Items have no such identifier. A miss fails with "Object '<id>' is not found or is not a <workflow object>."

Field references

A field's name is the name of its database column. A field whose name starts with UDF is a user-defined field. A field's default label is derived from its name: OID becomes ID, a _OID suffix becomes a space and ID, a _ID suffix is dropped, BR_Num becomes BR #, and underscores become spaces.

A read - the class list, both forms of /Dictionary, and the nested activity, collaborator, and attachment lists - matches a field's name exactly and case-sensitively. It never matches the field's caption, its default label, or an administrator's custom label. An unknown name in the requested fields, a filter, or a sort fails the whole request with Field '<name>' is unknown.

Writing a field in an action request resolves the name differently. The API first looks in the action's form for an object field, an activity field, or a form-only field whose field name, HTML counterpart, caption, or label matches. Only if that fails does it search the object and activity field dictionaries by caption. An unmatched name, or a matched name whose type cannot be determined, fails with "field is unknown". A create action with no form accepts any field of the object table. An activity field is named with the Activity. prefix, for example Activity.Time_Spent.

So the same word can be a valid field on a create or update request and an unknown field on a read request of the same class, and changing a field's custom label changes what an action request may say while leaving every read unchanged.

HTML fields

Under version v1, an HTML field returned when reading one object is converted to plain text. For which fields the response includes, see Read one object.

Under version v2, a read request that names the plain-text half of an HTML field pair is redirected to the HTML field.

An action always writes an HTML field through its HTML half: a request that names the plain-text half of the pair writes the HTML field. Under version v1 the submitted value is HTML-encoded; under version v2 it is stored as supplied.

Lookups and classification values

GET /Dictionary and POST /Dictionary return the entries behind one object class's reference field. On GET, the class and field are par_objectClass and par_refField; on POST, objectClass and refField in the body. Beside the class and the field, a /Dictionary request can carry a list query's fields, filters, and sort, and the names in them follow the read rule in Field references. The entries come back as a Fields / Data pair, as a class list's rows do.

A user-defined lookup field returns its custom values; an ordinary lookup field returns the rows of its lookup table, filtered by class where the lookup is scoped to one. Classification values - statuses, types, categories, lifecycle stages, and the ticket attributes priorities, urgencies, impacts, and closure codes - are lookups of that scoped kind: every value belongs to one object class, so /Dictionary returns them filtered by class. Other lookup tables, such as medium codes, budgets, or units of measure, are one list shared by the whole installation. A field that references an object rather than a reference table is rejected with its own message; reach those values through the object list routes instead.

Each ticket class has exactly one status that the product itself defines, named Closed, and its GUID is fixed in the product. That status cannot be deleted, although it can be renamed. The other statuses of a ticket class are not defined by the product.

Class GUID of the Closed status
Incident {1EF30595-098D-4082-80C6-052C72F2CA87}
Problem {F65F93B7-D122-4F3E-A15C-A1C759E25DC8}
Change Request {DEC7ED55-5623-46A3-824E-6DB8A407F2CB}
Service Request {E51A33D3-FFB4-47F9-92EF-0F31ABE85610}
Work Order {B524FF5E-092A-4745-AF48-98689383D3A2}

The product also fixes the GUID of one inactive status for each of the following classes, and supplies that status under the name shown:

Class GUID of the inactive status Name
Project Task {1AF76C74-6C45-439D-BA78-41FA79952829} Closed
Project {740FD29C-9E40-4C4E-A695-8E16B458D171} Inactive
SLA {BF80E884-92B4-43AC-A515-B9FC482E5D62} Inactive
Service {98BC7C31-941C-4596-BA47-30C39B5663EA} Inactive
Service Catalog Item {C075FF2A-99A5-42B0-8075-545D2C38FE87} Inactive
Approval Stage {DA125087-9078-433B-A2E8-5A0E6907663F} Inactive

Like the Closed status of a ticket class, these statuses cannot be deleted, although they can be renamed.

In a new 2026.1 database created with the Default Workflow (see Default Workflow Configuration), the Project status with that GUID is named Closed, and Approval Requests have an inactive status named Inactive with the GUID {7508CC98-EE19-44EA-88CD-30F4DFAB3EA6}. The product itself does not supply that Approval Request status.

When you set a reference field in an action request, you can supply a name instead of a GUID. The API resolves it against the lookup's table - by name, by OID, or through the object index for fields that reference objects - and category lookups match either of two name columns. A value that names a workflow object is matched against the same identifier an action request uses for that object (see Identification): the ticket number for a ticket, and the OID for most other workflow objects. A value that resolves to nothing fails with "object does not exist in database". A Boolean value accepts 0/1 or true/yes; anything else is read as false.

Wire names

In a JSON request or response, the members of an object keep the names the API declares for them, with no conversion to camel case, for example MessageList and AttachmentMaxSizeMB. A member whose value is one of a fixed set of options is sent as an integer, not as the option's name.

A short list of names is set by the API itself. Among them are the response envelope's success, errorCode, errorText, and responseObject (see Requests and Responses) and the Name, DataType, and Caption of each Fields entry in a list (see List and Read Objects). These are also among them and are spelled as shown:

Object Names
Record entry name, caption, value
List query body filters, sort, fields, offset, limit, searchText, viewName
Filter entry in filters name, value, operation
Sort entry in sort property, direction
/Dictionary body objectClass, refField

How a list query uses its names is described in List and Read Objects. All of these names are set for JSON only: the XML formatter does not apply them.

Record shape

Reading one object with GET /Object/{objectId} and reading one attachment's record with GET /Object/{objectId}/Attachments/{attachmentId} answer the same shape: a list of entries, each with a name, a caption, and a value. An attachment record has no shape of its own. GET /Profile answers the calling account's own Person record in the same shape.

Part JSON XML
The list of entries Items, an array <Items>
One entry An object with the keys name, caption, and value <Item>

In JSON, the entry keys are lower case.