---
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}`

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). Defaults to 0 if omitted. Ignored when milestonesEnabled is true.
  - `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 — Flag indicating whether milestones are enabled for this goal
  - `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, 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.

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)