Update Goal (v1.1)

put

https://{companyDomain}.bamboohr.com/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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

employeeId

string

required

employeeId is the employee ID with whom the goal is associated.

goalId

string

required

goalId is the goal ID for the specified employee.

Body Params

Required fields: title, sharedWithEmployeeIds, and dueDate. Omit optional fields that should remain unchanged. In particular, omit milestones unless adding new milestones; included milestones are appended, not reconciled or replaced.

title

string

required

The title of the goal

description

string

A detailed description of the goal

dueDate

date

required

The due date for the goal in YYYY-MM-DD format

percentComplete

integer

0 to 100

The percentage of completion for the goal (0-100). Defaults to 0 if omitted. Ignored when milestonesEnabled is true.

completionDate

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

array of integers

required

List of employee IDs with whom the goal is shared. Must include the employee ID of the goal owner.

sharedWithEmployeeIds*

alignsWithOptionId

ID of the option this goal aligns with

milestonesEnabled

boolean

Flag indicating whether milestones are enabled for this goal

deletedMilestoneIds

array of integers

List of milestone IDs to be deleted from the goal

deletedMilestoneIds

milestones

array of objects

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.

milestones

Responses

200A 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.

400The 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).

403Goal is not editable or insufficient permissions.

404The goal specified by the given goalId was not found.

500Something went wrong editing your goal.