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.
Related topics
- List and Read Objects - query the class list and read individual objects.
- Create Records and Run Actions