Utility endpoints provide access to metadata about the objects and fields available in the API. Rather than returning business data, such as students or enrolments, these endpoints return information that describes the structure of the API. This information helps you understand the available objects, their fields, and the values that can be used when building API requests.
Key Concepts
Before using the utility endpoints, it is important to understand three concepts that are used throughout the API documentation and responses.
Objects
Objects represent the different types of records managed by the system. Each object corresponds to a business entity, such as Students, Agents, Offers, or Enrolments, and defines the fields that can be stored for that type of record.
Objects can also be related to one another through lookup fields. For example, an Enrolment record is linked to a Student, and an Offer can be linked to an Agent.
Fields
Fields are the individual data elements that make up an object. Each field stores a single piece of information about a record, such as a student's First Name, Date of Birth, Email Address, or Status.
Every field has its own characteristics, including its data type, description, and other attributes that define how the field can be used.
Picklists
A picklist is a type of field that allows users to select one or more values from a predefined list of options. Picklists help ensure data is entered consistently and prevent invalid values from being used.
For example, the Country of Birth field is a picklist that contains the list of supported countries.
Understanding Metadata
Metadata is simply information that describes the objects and fields available in the API.
For example, before creating a Student record, you may need to determine which fields are available, which fields are required, and what type of data each field accepts. Rather than relying on hard-coded definitions, you can retrieve this information using the utility endpoints.
For instance, the Get Object Fields endpoint returns the list of fields for a selected object, together with information such as the field name, description, data type, and other attributes. If a field is a picklist, you can then use the corresponding utility endpoint to retrieve its valid values.
By using the metadata provided by these endpoints, applications can discover the API structure dynamically and remain compatible as new fields and objects are added.
For a complete list of utility endpoints, refer to the Utilities group in the API Reference.