Update an assigned goal definition and reconcile assignees

  • Updated on Oct 9, 2026
  • Published on Oct 5, 2026
Prev Next
Patch
/goals/definitions/{id}

Updates an assigned goal definition and reconciles the assignee set to match assignees. assigner is required (LMS ref of an active tenant user). api-service resolves all refs, then impersonates the assigner on goals-service with the api-service role (manager/authorityToken checks are skipped). Goal status is derived from task completion and cannot be set on this path.

This is a full-field replace, not a sparse PATCH. tasks and assignees are the complete desired sets — omitted tasks or assignees are removed. Optional fields left out keep their current value; send an explicit null to clear them (description, dueDate, boostToLevel).

Security
HTTP
Type basic

HTTP Basic authentication using your Tenant ID and API secret.

  • Username is the Tenant ID (i.e. eu-west-2_AbcdEfghI)
  • Password is the API secret you would have received.

You can also authenticate using OAuth 2.0 client credentials (oauth2 security scheme) instead of Basic auth.

OAuth

OAuth 2.0 client credentials authentication.

Use the following token endpoints (replace :tenantId with your Tenant ID):

  • Public API access tokens

    • Staging: https://public.api.learnstaging.link/oauth2/token/:tenantId
    • Production: https://public.api.learn.link/oauth2/token/:tenantId
    • Staging MEA: https://public.api.meastaging.learn.tech/oauth2/token/:tenantId
    • Production MEA: https://public.api.mea.learn.tech/oauth2/token/:tenantId

  • Webhooks access tokens

    • Staging: https://user.api.learnstaging.link/oauth2/token/:tenantId
    • Production: https://user.api.learn.link/oauth2/token/:tenantId
    • Staging MEA: https://user.api.meastaging.learn.tech/oauth2/token/:tenantId
    • Production MEA: https://user.api.mea.learn.tech/oauth2/token/:tenantId

All access tokens must be sent using the Authorization: Bearer <access_token> header.

Scopes

For API access (non-webhooks), the following scopes are available:

  • api/all – Full read and write access to the API.
  • api/read – Read-only access to the API.
  • api/write – Write access to the API.

For webhooks, the following scopes are available:

  • api/webhooks – Access to webhook functionality.
  • api/all – Full read and write access to the API, including webhooks.

Tokens must include appropriate scopes for the endpoints you wish to call.

FlowClient Credentials
Token URLhttps://public.api.learn.link/oauth2/token/:tenantId
Scopes:
api/writeWrite access to the API.
Path parameters
id
stringRequired

The goal definition ID

Pattern^[0-9a-fA-F]{24}$
Example63f57d805d8ecbf46f5b5278
Body parameters
Expand All
object
assigner
string Required

LMS reference of the acting assigner. The tenant must have an active user with that LMS ref; it becomes createdBy on newly assigned goals.

Min length1
Max length255
Pattern\S
Examplemanager-12345
assignees
Array of string Required

Full desired assignee LMS-ref set after reconciliation

Min items1
Max items100
Unique itemstrue
Example[ "employee-1", "employee-2" ]
string
Min length1
Max length255
Pattern\S
title
string Required
Min length1
Max length100
Pattern\S
ExampleQ3 development goal
skill
string Required

Name of a skill that already exists in the organisation. A name that is not a skill is rejected with 422.

Min length1
Max length100
Pattern\S
Examplecommunication
description
string | null
Max length500
dueDate
string (date-time) | null
canLearnerAdd
boolean Required
willBoostLevel
boolean Required
boostToLevel
integer | null

When sent, must be an enabled skill level value for the tenant. The 422 lists the accepted values. A tenant with no skill levels configured accepts the defaults: Beginner (1024), Intermediate (2048) and Advanced (3072). A tenant can define different ones.

Minimum1.0
Maximum2147483647.0
Example1024
tasks
Array of object (PatchGoalTaskRequest) Required
Min items1
Max items100
object
id
string

Existing task id. Omit to create a new task.

Pattern^[0-9a-fA-F]{24}$
Example63f8c54a8cb9790c99de077a
title
string Required
Min length1
Max length100
ExampleComplete onboarding module
description
string | null
Max length500
type
string Required
Valid values[ "basic", "content" ]
Examplebasic
contentIds
Array of string

Empty or omitted for basic tasks; required and non-empty for content tasks. Each id must be a 24-character hex ObjectId of content that exists in the tenant. A missing id is rejected with 422.

string
Min length24
Max length24
Pattern^[a-fA-F0-9]{24}$
evidenceRequired
boolean
Defaultfalse
approvalRequired
boolean
Defaultfalse
rank
integer Required
Minimum1.0
Example1
OneOf
object
object
type
string
Valid values[ "basic" ]
contentIds
Array of string
Max items0
string
Min length24
Max length24
Pattern^[a-fA-F0-9]{24}$
id
string

Existing task id. Omit to create a new task.

Pattern^[0-9a-fA-F]{24}$
Example63f8c54a8cb9790c99de077a
title
string
Min length1
Max length100
ExampleComplete onboarding module
description
string | null
Max length500
evidenceRequired
boolean
Defaultfalse
approvalRequired
boolean
Defaultfalse
rank
integer
Minimum1.0
Example1
object
object
type
string
Valid values[ "content" ]
contentIds
Array of string Required
Min items1
Max items100
string
Min length24
Max length24
Pattern^[a-fA-F0-9]{24}$
id
string

Existing task id. Omit to create a new task.

Pattern^[0-9a-fA-F]{24}$
Example63f8c54a8cb9790c99de077a
title
string
Min length1
Max length100
ExampleComplete onboarding module
description
string | null
Max length500
evidenceRequired
boolean
Defaultfalse
approvalRequired
boolean
Defaultfalse
rank
integer
Minimum1.0
Example1
Responses
200

The updated goal definition

Expand All
object

An assigned goal definition shared across assignees.

id
string
Example63f57d805d8ecbf46f5b5278
title
string
ExampleQ3 development goal
description
string | null
skill
string
Examplecommunication
dueDate
string (date-time) | null
canLearnerAdd
boolean
willBoostLevel
boolean
boostToLevel
integer | null
completedAt
string (date-time) | null
author
object | null
id
string
fullName
string
hasPicture
boolean
usersSummary
object | null
count
integer
users
Array of object
object
id
string
fullName
string
tasks
Array of object (GoalDefinitionTask)
object
id
string
type
string
title
string
description
string | null
contentIds
Array of string
string
evidenceRequired
boolean
approvalRequired
boolean
rank
integer
401

Unauthorized

object

Unauthorized

status
number
Example401
error
string
ExampleUnauthorized
message
string
403

Forbidden

object

Forbidden

status
number
Example403
error
string
ExampleForbidden
message
string #deprecatedtemplate# #additional-property-template#
OneOf
string
string
object
object
404

Not Found

object

Not found

status
number
Example404
error
string
ExampleNot Found
message
string #deprecatedtemplate# #additional-property-template#
OneOf
string
string
object
object
415

Unsupported Media Type — Content-Type must be application/json

Expand All
id
string
ExampleUNIQUEREFERENCE111000
timestamp
string
Example2020-03-09T22:18:26.625Z
eventType
string
Valid values[ "user_joined", "user_updated", "user_suspended" ]
message
object

The request could not be processed due to a validation error

status
number
Example422
error
string
ExampleUnprocessable Entity
message
string
ExampleThe startDate must be in a valid ISO 8601 format
422

Unprocessable Content

object

Unprocessable Content

status
number
Example422
error
string
ExampleUnprocessable Content
message
string #deprecatedtemplate# #additional-property-template#
OneOf
string
string
object
object
502

Bad Gateway

object

The request could not be completed because a service it depends on failed. For write operations the content was not modified.

status
number
Example502
error
string
ExampleBad Gateway
message
string
ExampleThe request could not be completed because a service it depends on is unavailable. Please retry shortly.
default

Internal Server Error

object

Internal Server Error

status
number
Example500
error
string
ExampleInternal Server Error
message
string

© 2025 Thrive Learning

Website & cookies policy Terms and Conditions Privacy policy