---
updatedAt: 2025-12-21T10:30:58.000Z
---

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.

# Explore Goals API

Understand the basic concepts of Goals in Bob and how to utilize them with the Public API

Goals are part of the <Anchor label="Talent module" target="_blank" href="https://help.hibob.com/hc/en-us/articles/13543200033041">Talent module</Anchor> 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 <Anchor label="Getting started with Goals" target="_blank" href="https://help.hibob.com/hc/en-us/articles/4409792069649-Getting-started-with-Goals">Getting started with Goals</Anchor>.

To review the Goals reference guide, see [Goals API reference](https://apidocs.hibob.com/reference/goals).

## Key concepts

<Accordion title="Goal types">
  Goals are categorized by type, which defines their level in the organizational structure. Types include:

  * <strong>Company </strong>(built-in) – Always the top-level type
  * <strong>Custom </strong>– User-defined types (e.g., Department, Team), each linked to a list in Bob.
  * <strong>Individual</strong> (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 <a href="https://apidocs.hibob.com/reference/get_company-named-lists-listname">Get a specific company list by name</a> endpoint. To learn more, see <a href="https://apidocs.hibob.com/docs/fields-metadata"> fields and lists metadata</a>.
</Accordion>

<Accordion title="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

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

<Accordion title="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:

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

<Accordion title="Key results progress (check-in)">
  Check-ins in Bob are used to report on the progress of a goal’s key results.

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

<Accordion title="Goal cycles and weight for performance review">
  A **goal cycle** lets admins define a timeframe for a goal.
  **Weights for permformance reviews** can be assigned to each goal in a cycle, helping teams clearly understand which objectives matter most.

  These weights influence overall performance scores for employees when weighted goals are included in the review form in a performance cycle. This feature helps ensure that both managers and employees are aligned on what matters most and how it will be measured.

  The Goals API allows to read goal cycles, assign goals to cycles and featch the cycle and weight for performance review linked to the goal.

</Accordion>

## Permissions

Before accessing goals data, ensure the service user has permission to access the relevant information, just as you would when assigning permissions to a user in Bob.

To learn more, see [Goals required permissions](https://apidocs.hibob.com/reference/goals#required-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.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Endpoints
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        * [Get metadata for Goal Types](https://apidocs.hibob.com/reference/get_goals-goal-types-metadata)
        * [Get metadata for Goals](https://apidocs.hibob.com/reference/get_goals-goals-metadata)
        * [Get metadata for Key Results](https://apidocs.hibob.com/reference/get_goals-goals-key-results-metadata)
      </td>

      <td>
        Use these endpoints to fetch the goals, goal types, and key results.
      </td>
    </tr>

    <tr>
      <td>
        * [Search Goal Types](https://apidocs.hibob.com/reference/post_goals-goal-types-search)
        * [Search Goals](https://apidocs.hibob.com/reference/post_goals-goals-search)
        * [Search Key Results](https://apidocs.hibob.com/reference/post_goals-goals-key-results-search)
      </td>

      <td>
        Use these endpoints to fetch the goals, goal types, and key results.
      </td>
    </tr>

    <tr>
      <td>
        * [Create Goal](https://apidocs.hibob.com/reference/post_goals-goals)
        * [Update Goal](https://apidocs.hibob.com/reference/patch_goals-goals-goalid)
        * [Delete Goal](https://apidocs.hibob.com/reference/delete_goals-goals-goalid)
        * [Update Goal Status](https://apidocs.hibob.com/reference/patch_goals-goals-goalid-status)
      </td>

      <td>
        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..
      </td>
    </tr>

    <tr>
      <td>
        * [Create Key Results](https://apidocs.hibob.com/reference/post_goals-goals-goalid-key-results)
        * [Update Key Results Details](https://apidocs.hibob.com/reference/patch_goals-goals-goalid-key-results)
        * [Delete Key Result](https://apidocs.hibob.com/reference/delete_goals-goals-goalid-key-results-keyresultid)
        * [Update Key Results Progress](https://apidocs.hibob.com/reference/patch_goals-goals-goalid-key-results-progress)
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        * [Get goal cycle metadata](https://apidocs.hibob.com/reference/get_goals-goal-cycles-metadata)
        * [Search for goal cycles](https://apidocs.hibob.com/reference/post_goals-goals-goal-cycles-search)
      </td>

      <td>
        Use these endpoints to fetch the goal cycles metadata and goal cycles details
      </td>
    </tr>
  </tbody>
</Table>

## API Workflows

<Accordion title="1. Fetch list values" icon="fa-list">
  Some fields require values from Bob’s named lists.

  Use the [Named Lists API](https://apidocs.hibob.com/reference/get_company-named-lists-listname) endpoint to fetch values for:

  * `currency` — used for currency-type key results
  * `typeListItem` — if your goal type is linked to a custom list
</Accordion>

<Accordion title="2. Create Goal" icon="fa-plus-square">
  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)
</Accordion>

<Accordion title="3. Create Key Results" icon="fa-tasks">
  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)
</Accordion>

<Accordion title="4. Update Progress (Check-in)" icon="fa-check-circle">
  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.
</Accordion>

<Accordion title="5. Change Goal Status" icon="fa-flag-checkered">
  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.
</Accordion>

<Accordion title="6. Search for Goals" icon="fa-search">
  Use the [`POST /goals/goals/search`](https://apidocs.hibob.com/reference/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.
</Accordion>

## 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`.