v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB

Goals

Public API

Create Goal

Create a new goal for an employee. To create a simple goal without milestones, omit the milestones field; the goal's progress can then be changed with update-goal-progress. To create a milestone-based goal, provide milestones as a non-empty array of { "title": string } objects; the goal's percent complete is then derived from milestone completion and should be changed via update-goal-milestone-progress. Sending milestones: null is treated as omitted (creates a simple goal).

OAuth Scopes: goal.write

post/api/v1/performance/employees/{employeeId}/goals

Path parameters

employeeIdstring required

The internal employee ID of the employee who owns the new goal.

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

Initial percentage of completion for a simple goal (0-100). Defaults to 0 if omitted. Ignored when milestones is provided; milestone-based goals derive percent complete from milestone completion and should be updated via update-goal-milestone-progress.

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.

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

Example request

{
  "title": "New Goal To update",
  "description": "This should be fun!",
  "dueDate": "2025-12-17",
  "sharedWithEmployeeIds": [
    1234,
    5678
  ],
  "milestones": [
    {
      "title": "Surprise, it is a milestone"
    },
    {
      "title": "Now there are two of them!"
    }
  ]
}

Response

A goal object that includes the new goal.

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