Introduction

We're gradually moving toward a new model for our Public API, one that's object-based, where each object has a clear structure, predictable references, and its own metadata.

This article explains the key ideas behind this model, how the data is structured, and what to expect when working with these endpoints.

Standardizing how object data is exposed allows:

A consistent field structure
Predictable reference behavior
Support for customization and localization
A scalable approach to bulk reads and writes

Important notes:

To support a gradual shift to the object-based model, some objects, like Positions, may have both legacy and object-based endpoints. For example, a search endpoint may return data in the legacy format, while newly introduced create and update endpoints for the same object follow the object-based structure.
The underlying field IDs and other metadata fields will remain consistent to ensure smooth usage with both approaches.

Key principles

These are the key principles of the object-based approach:

All object data lives under theitems array:
- Simple fields (text, numbers, enums) return a primitive value, and may return a display value (e.g. for enums).
- Reference and object fields return structured data or the ID of the sub-object.
Field IDs may have different formats, so for example Goals will have a description field while position will have /position/description field. Always use the ID as received from the metadata endpoint.
Endpoint URLs include the module name and the resource name. For example: goals/goal-types
Metadata endpoints tell you what fields are available and how to use them. You’re expected to build requests dynamically using metadata (rather than hardcoding field names), especially as object definitions become customizable.
Reference fields by default, reference to other objects return only the ID in the response JSON. One-to-one references may return full objects; one-to-many data is exposed via separate endpoints.
Search endpoints use POST with a consistent structure for fields, filters, and pagination.

Note: Not all endpoints currently enforce pagination. You’ll find a note in each API's documentation that clearly states whether pagination is currently enforced.

Human-readable values are included in the response when relevant, for example, when the value is an item in a list.
Access control is built-in. Fields that the service user isn’t authorized to access are automatically excluded from results. If the whole object cannot be accessed, a permissions/authorization error is returned.
PATCH is the standard for updates; PUT is used rarely and only for full replacements.

Object-based payload example

{
  "items": [
    {
      "objectType": "goal",
      "fields": {
        "id": {
          "value": 1
        },
        "title": {
          "value": "Sample Title 1"
        },
        "description": {
          "value": "Sample description"
        },
        "startDate": {
          "value": "2025-01-01"
        },
        "dueDate": {
          "value": "2025-10-10"
        },
        "typeId": {
          "value": 9292
        },
        "category": {
          "value": "Company"
        },
        "status": {
          "value": "completed"
        },
        "owner": {
          "value": 123123123
        },
        "isPrivate": {
          "value": false
        },
        "alignedGoal": {
          "value": 9797
        },
        "hasKeyResults": {
          "value": true
        },
        "isActive": {
          "value": false
        }
      }
    }
  ],
  "responseMetadata": {
    "totalCount": 0,
    "pageSize": 0
  },
  "nextCursor": "string",
  "errors": {}
}

Metadata

Each object includes a metadata endpoint that describes its fields and their types. This helps to dynamically understand how to interpret and display object data.

Metadata endpoints are placed under the object’s base path, for example: /goals/goals/metadata (first goals is the module name)

A standard format for metadata responses is returned for object-based entities.

Metadata response:

{
  "items": [
    {
      "id": "goal",
      "displayName": "The Goal Object",
      "fields": [
        {
          "id": "id",
          "type": {
            "dataType": "number"
          },
          "propertiesValues": {
            "isRequired": {
              "value": false
            },
            "displayName": {
              "value": "ID"
            },
            "description": {
              "value": "The unique identifier for the goal"
            }
          }
        },
        {
          "id": "title",
          "type": {
            "dataType": "string"
          },
          "propertiesValues": {
            "isRequired": {
              "value": false
            },
            "displayName": {
              "value": "Title"
            },
            "description": {
              "value": "The title of the goal"
            }
          }
        }
      ]
    }
  ]
}

Referencing to other objects

Reference fields are used to connect objects together. Depending on the type, the data returned may vary:

Type	Returned Data	Example
Enum or simple reference	Just the ID	`"id": { "value": "123" }`
One-to-one sub-object	Full object with fields	budget within a goal
One-to-many sub-objects	Use relevant endpoints	Get the goal's key results

Relevant endpoints

Endpoints that follow the object-based model:

Goals - all endpoints
Workforce planning - only endpoints that create or update positions, position openings and budgets.