Explore Goals API

Goals are part of the Talent module in Bob. They help teams and individuals create, measure, and collaborate on personal and company-wide objectives. The Goals API enables integration with external goal management systems, allowing you to create goals in Bob with key results, update their status, and report on their progress.

To learn more about Goals in the Bob platform, see Getting started with Goals.

To review the Goals reference guide, see Goals API reference.

Key concepts

Goal types

Goals are categorized by type, which defines their level in the organizational structure. Types include:

Company (built-in) – Always the top-level type
Custom – User-defined types (e.g., Department, Team), each linked to a list in Bob.
Individual (built-in) – Always the bottom-level type

For example, if you define two custom types, the hierarchy might look like this:

Goal Type	Custom	Order	Field/list
Company	false	0	--
Department	true	1	departments-list
Team	true	2	teams-list
Individual	false	3	--

Notes:

This order governs goal alignment: a goal can only be aligned with another goal goal that comes before it in the list. For example, a Department-level goal (order: 1) can align with a Company goal (order: 0), but not with a Team or an Individual goal.
Custom goal types are connected to list fields in Bob, which define the values users can choose from when creating a goal. For example, if a custom goal type called “Department” is linked to the departments list, users should assign a specific department to the goal. When using the public API you can retrieve the available list values, using the Get a specific company list by name endpoint. To learn more, see fields and lists metadata.

Goals

A goal in Bob is a structured way to track progress using measurable outcomes, following the OKR (Objectives and Key Results) methodology. Each goal:

Belongs to a specific goal type (based on the hierarchy above)
Has a status (in-progress or complete)
Is owned by an employee
May include measurable key results
May optionally be aligned with another goal of a higher order

Note: When using the public API, the goal’s status update is performed using a dedicated /status endpoint.

Key results

Key results are the quantifiable outcomes used to measure goal progress. Each key result is linked to a goal, and includes: title, description, measure type, target value and the current value (progress). The measure type determine how the key result will be measured:

Percentage (%): Always 100%; can omit target value on create
Numeric: Any number ≥ 1; rquires target value on create
Currency: Requires target value and currency on create
Complete/Incomplete: Can omit target value on create (defaults to true)

Key results progress (check-in)

Check-ins in Bob are used to report on the progress of a goal’s key results.

Note: When using the public API, progress updates are performed using a dedicated /key-results/progress endpoint.

Permissions

The service user accessing the api should be granted the relevant permissions based on the data they need to access. Goals have granular permissions based on the goal type. The service user should be granted the permissions for all the goal types you want to access via the API.

This includes:

Features > Goals: Grants access to view, create, edit, and check in goals. This is required for the service user to be able to access goals in general. Must be granted for each goal type explicitly.
People’s Data > Goals: Grants access to view, create, edit, or check-in goals owned by other employees. This is required for the service user to access people’s goals. Must be granted for each goal type explicitly.
People’s Data > Access data for: Specify the audience for which this service user will have access. For example, the service user may have permission to access “goals owned by other employees” but they still need to define who is included in their scope.

Notes:

Each permission should be set separately for each goal type, including custom goal types you add.
No need to grant “my own” permissions because the service user is not an employee.

To learn more about how to set permissions for a service user, see Permissions.

Goals endpoints

The Goals API uses our new object-based API model, which introduces consistent data structures, predictable references, and self-describing metadata. This approach enables greater flexibility, customization, and scalability when reading or writing data. Metadata endpoints help you dynamically build requests, making integrations more robust and future-proof.

Action	Description	Endpoints
Metadata	Use these endpoints to obtain the fields of each entity within the Goals module. The metadata returns all the field IDs, and other properties, allowing you to use them later in queries to fetch the field data.	Get metadata for Goal Types Get metadata for Goals Get metadata for Key Results
Search	Use these endpoints to fetch the goals, goal types, and key results.	Search Goal Types Search Goals Search Key Results
Goals Write	Use these endpoints to create, update, and delete goals. Note that goal status should be updated via a dedicated endpoint, as it allows adding a comment when updating the progress status.	Create Goal Update Goal Delete Goal Update Goal Status
Key-results Write	Use these endpoints to create, update, and delete key results. Key results are always tied to a specific goal. Updating the key results progress (check-in) does not update the goal status, and you should update the status separately.	Create Key Results Update Key Results Details Delete Key Result Update Key Results Progress

API Workflows

1. Fetch list values

Some fields require values from Bob’s named lists.

Use the Named Lists API endpoint to fetch values for:

currency — used for currency-type key results
typeListItem — if your goal type is linked to a custom list

2. Create Goal

Use the POST /goals/goals endpoint.

You must include:

title
startDate and dueDate
typeId (from the goal type search)
owner
isPrivate

Optional fields:

description
alignedGoal
typeListItem (if applicable)

3. Create Key Results

Use the POST /goals/goals/{goalId}/key-results endpoint.

You must include for each key result:

title
measureType (e.g. numeric, percentage, boolean, currency)
target

If measureType is currency, also include:

currency and currencySymbol (from the currency named list)

4. Update Progress (Check-in)

Use the PATCH /goals/goals/{goalId}/key-results/progress endpoint.

This lets you:

Update one or more key results’ currentValue
Optionally add a comment (e.g. “Weekly check-in”)

This does not change the goal status.

5. Change Goal Status

Use the PATCH /goals/goals/{goalId}/status endpoint.

Supported status values:

onTrack
offTrack
completed
incomplete
other

You can also include a comment explaining the update.

6. Search for Goals

Use the POST /goals/goals/search endpoint to retrieve goals using filters.

You can filter by:

status — e.g. onTrack, completed
isPrivate — true or false
typeId — to filter by goal type

You can also combine filters to narrow down results.

Use case

To integrate with an external goal management system, you can follow this workflow:

Fetch goal types from Bob: Use the API to retrieve available goal types and understand their hierarchy.
Map goal types: Match Bob’s goal types (e.g., Company, Department) to types used in your system.
Fetch employee data: Use the Employee Data API to get employee IDs, which you’ll need to assign goal ownership.
Create goals in Bob: For each goal from your external system, create a goal in Bob using the appropriate type and assign it to an owner. If applicable, include key results. Store the returned goalId for later use.
Maintain goal hierarchy: When creating or updating a goal, use the alignedGoal field to indicate strategic alignment. Only align to goals of a higher order.
Update goals as needed: Use the stored goalId to fetch and update goals in Bob as changes occur (e.g., title, time frame, status, key results).
Check-in on goals: Report progress using the /key-results/progress endpoint.
You can also update the goal’s status (e.g., close or reopen).
Handle deletions: If a goal is deleted in your system, delete the corresponding goal in Bob using the stored goalId.