BAbamboohr
Goals
Public API

Update Goal (v1.1)

Changed on

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

put/api/v1_1/performance/employees/{employeeId}/goals/{goalId}

Request

Path parameters

employeeIdstring required

The internal employee ID of the employee the goal is associated with.

goalIdstring required

goalId is the goal ID for the specified employee.

Request body

titlestring required

The title of the goal

descriptionstring

A detailed description of the goal

dueDatestring date required

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

percentCompleteinteger

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.

completionDatestring 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.

sharedWithEmployeeIdsinteger[] required

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

alignsWithOptionIdinteger nullable

ID of the option this goal aligns with

milestonesEnabledboolean 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.

deletedMilestoneIdsinteger[]

List of milestone IDs to be deleted from the goal

Example request

{
  "title": "Edited Goal With Milestones",
  "description": "Lets go!",
  "dueDate": "2024-03-17",
  "sharedWithEmployeeIds": [
    1234,
    5678
  ],
  "milestonesEnabled": true,
  "deletedMilestoneIds": [
    490
  ]
}

Response

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.

Example response

{
  "goal": {
    "id": "4",
    "title": "Complete Documentation Epic",
    "description": "Document every endpoint for the goals API.",
    "percentComplete": 78,
    "dueDate": "2025-12-31",
    "completionDate": "2025-12-17T10:30:00Z",
    "lastChangedDateTime": "2025-12-17T10:30:00Z",
    "status": "in_progress",
    "milestones": [
      {
        "id": 2,
        "employeeGoalId": 12,
        "title": "Sell 15 Doohickeys",
        "completedDateTime": "2025-04-10T15:36:38Z",
        "lastUpdateDateTime": "2025-04-10T15:36:38Z",
        "lastUpdateUserId": 24
      }
    ],
    "actions": {
      "canEditGoalProgressBar": true
    }
  }
}

Changes

  • 922fc15f43a7Revision changes
    • info

      api operation id update-goal-v1.1 removed and replaced with update-goal-v1_1

    • info

      request property list-of-types was widened by adding types null to media type application/json