Sign in

v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB
Goals
Public API

Update Goal (v1.1)

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}

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). Defaults to 0 if omitted. Ignored when milestonesEnabled is true.

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

Flag indicating whether milestones are enabled for this goal

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