---
title: "Update Goal (v1.1)"
method: PUT
path: "/api/v1_1/performance/employees/{employeeId}/goals/{goalId}"
tags: ["Goals", "Public API"]
---

# Update Goal (v1.1)

`PUT /api/v1_1/performance/employees/{employeeId}/goals/{goalId}`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1_1/performance/employees/{employeeId}/goals/{goalId}`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `goal.write`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1_1/performance/employees/:employeeId/goals/:goalId/put.ts> (a function with typed inputs; its response is checked against the schema)

Update a goal's top-level fields and optionally add or delete milestones. Milestone handling is not a full replace or upsert: objects passed in `milestones` are always added as new milestones, even if their titles match existing milestones. To keep existing milestones unchanged while editing title, description, due date, sharing, or alignment, omit the `milestones` field. To remove milestones, pass their IDs in `deletedMilestoneIds`. There is no field for editing an existing milestone title in place. Note: Compared to "Update Goal (v1)", this version adds milestone updates.

OAuth Scopes: goal.write

## Path parameters

- `employeeId` string, required
- `goalId` string, required

## Request body

- object
  - `title` string, required: The title of the goal
  - `description` string: A detailed description of the goal
  - `dueDate` string, date, required: The due date for the goal in YYYY-MM-DD format
  - `percentComplete` integer: The percentage of completion for the goal (0-100). Ignored when milestonesEnabled is true (progress is derived from milestones). When milestonesEnabled is false, defaults to 0 if omitted. When milestonesEnabled is omitted, existing progress is left unchanged unless this value is supplied.
  - `completionDate` string, date, nullable: The date when the goal was completed in YYYY-MM-DD format. Only valid when percentComplete is 100; providing this field with any other percentComplete value will result in an error. Ignored when milestonesEnabled is true.
  - `sharedWithEmployeeIds` integer[], required: List of internal employee IDs with whom the goal is shared. Must include the internal employee ID of the goal owner.
  - `alignsWithOptionId` integer, nullable: ID of the option this goal aligns with
  - `milestonesEnabled` boolean, nullable: Whether milestones are enabled for this goal. true enables milestones and derives progress from them; false disables milestones (progress becomes manual via percentComplete). Omit the field to leave the goal's milestones and progress unchanged; milestones and deletedMilestoneIds are only applied when this is true.
  - `deletedMilestoneIds` integer[]: List of milestone IDs to be deleted from the goal
  - `milestones` object[]: Optional. New milestones to add to the goal. Each object in this array creates a new milestone — even if its title matches an existing milestone. Do not include existing milestones here unless you intentionally want duplicates. To remove milestones, use `deletedMilestoneIds`.
    - `title` string: The title of the milestone

## Response `200`

A successful response indicates that all the requested changes were made. The content of the response will be the goal response object for the specified goalId.

- TransformedApiEmployeeGoalDetails
  - `goal` object: An individual goal
    - `id` string: The id of the goal.
    - `title` string: Title of the goal.
    - `description` string: A description of the goal.
    - `percentComplete` integer: A percentage (0-100) that denotes how complete the goal is.
    - `alignsWithOptionId` string, nullable
    - `sharedWithEmployeeIds` integer[]: Ids of the employees that have access to this goal.
    - `dueDate` string: The due date of the goal.
    - `completionDate` string, nullable: ISO 8601 UTC timestamp of when the goal was completed.
    - `lastChangedDateTime` string, nullable: ISO 8601 UTC timestamp of when the goal was last modified.
    - `status` 'in_progress' | 'completed' | 'closed': The status of the goal.
    - `milestones` object[], nullable: All milestones for the individual goal. This array will not exist if milestones are not selected for this goal.
      - `id` integer: The id of the milestone.
      - `employeeGoalId` integer: The id of the goal which encompasses this milestone.
      - `title` string: The title of the milestone.
      - `currentValue` number, nullable: The current value for a numeric milestone. This number will be rounded to the nearest hundredth. On the creation of a numeric milestone this value will automatically be set to the start value of the milestone. If the milestone is a simple checkbox milestone, this value will always be null.
      - `startValue` number, nullable: The starting value for a numeric milestone. This number will be rounded to the nearest hundredth. If the milestone is a simple checkbox milestone, this value will always be null.
      - `endValue` number, nullable: The end goal for a numeric milestone. This number will be rounded to the nearest hundredth. If the milestone is a simple checkbox milestone, this value will always be null.
      - `completedDateTime` string: The date and time in which the goal has been completed. If the goal is not completed the value will be null.
      - `lastUpdateDateTime` string: The date and time in which the goal was last updated.
      - `lastUpdateUserId` integer: The ID of the user who last updated this milestone.
    - `actions` object, nullable: Actions that are available to a goal with milestones enabled. This object will not appear on a goal without milestones.
      - `canEditGoalProgressBar` boolean: Can the user edit the progress bar of this goal.
      - `canEditGoalMilestoneProgressBar` boolean: can the user edit the progress of a milestone in this goal.

## Other responses

- `400`: The request is invalid. Possible causes: sharedWithEmployeeIds is not an array or missing the goal owner, percentComplete is out of range (0–100), the goal has milestones and percentComplete cannot be manually updated, milestones or deletedMilestoneIds were supplied without setting milestonesEnabled to true, or the goal is a cascading goal (not supported by this endpoint).
- `403`: Goal is not editable or insufficient permissions.
- `404`: The goal specified by the given goalId was not found.
- `500`: Something went wrong editing your goal.

## Changes

- **2026-11-03** `922fc15f43a7`: 2 info
  - api operation id `update-goal-v1.1` removed and replaced with `update-goal-v1_1`
  - request property `milestonesEnabled` list-of-types was widened by adding types `null` to media type `application/json`

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1_1/performance/employees/:employeeId/goals/:goalId/put.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)