Update a user

  • Published on May 21, 2026
  • 4 minute(s) read
Prev Next
Patch
/users/ref/{ref}

Updates an existing user account identified by their ref. Only fields included in the request body are updated; omitted fields retain their existing values. Fields explicitly set to null will be cleared.

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
Path parameters
ref
stringRequired

The user ref

Examplexyzabc
Body parameters
updateUser

Partially update a user

Updates only the fields provided. Fields not included in the request are left unchanged. Set a field to null to clear it.

"{\n  \"firstName\": \"Tom\",\n  \"jobTitle\": \"Senior Director\",\n  \"managerRef\": null,\n  \"additionalFields\": {\n    \"department\": \"Product\"\n  }\n}\n"
Expand All
object

The input to update an existing user account.

All fields are optional; omitted fields retain their existing values. Fields explicitly set to null will be cleared where permitted.

firstName
string | null

The given name of the individual

Max length255
ExampleThomas
lastName
string | null

The family name of the individual

Max length255
ExampleJefferson
email
string (email)

The email address for the user

Max length320
Exampleuser@thrivelearning.com
loginMethod
string | null

How the user logs in

Exampleemail
role
string

The role assigned to this individual

Valid values[ "administrator", "learneradmin", "learner" ]
Examplelearner
jobTitle
string | null

The name of this individual's role in your organisation

Max length500
ExampleDirector
managerRef
string | null

Your organisation's unique identifier for this individual's line manager

Max length500
ExampleUID0034234555
startDate
string (date-time) | null

The date this individual started working with your organisation

Example2021-08-19T18:00:00Z
endDate
string (date-time) | null

The date this individual left your organisation

timeZone
string

The user's preferred timezone

ExampleEurope/London
languageCode
string

The user’s preferred language. If not provided the tenant default is used.

One caveat is that the tenant may only use the languages they have requested.

Valid values[ "cs", "de", "en-gb", "en-us", "es", "es-mx", "fi", "fr", "hu", "id", "it", "ja", "ja-jp", "kn-in", "ms-my", "nl", "pl", "pt", "sk", "sv", "th", "tr", "zh-cn" ]
Defaultnull
Exampleen-gb
sso
boolean

Whether this account is managed by an Authentication provider or not.

Exampletrue
domain
string

The domain this individual is associated with

Max length255
Exampletenant.learn.link
additionalFields
object

Custom field key-value pairs matching your configured custom fields.

Responses
200

OK

Expand All
object

A user lifecycle resource returned by the v2 user lifecycle endpoints

id
string
Example6143eedfd39243e830bdbb8c
loginMethod
string
Exampleemail
ref
string
ExampleUID30084022
email
string
Exampleuser@thrivelearning.com
firstName
string
ExampleThomas
lastName
string
ExampleJefferson
role
string
Valid values[ "administrator", "learneradmin", "learner" ]
Examplelearner
jobTitle
string
ExampleDirector
managerRef
string | null
ExampleUID0034234555
startDate
string (date-time) | null
Example2021-01-01T09:00:00Z
endDate
string (date-time) | null
Example2021-06-11T16:00:00Z
timeZone
string
ExampleEurope/London
languageCode
string

The user’s preferred language. If not provided the tenant default is used.

One caveat is that the tenant may only use the languages they have requested.

Valid values[ "cs", "de", "en-gb", "en-us", "es", "es-mx", "fi", "fr", "hu", "id", "it", "ja", "ja-jp", "kn-in", "ms-my", "nl", "pl", "pt", "sk", "sv", "th", "tr", "zh-cn" ]
Defaultnull
Exampleen-gb
active
boolean

Whether the account is active or suspended

Exampletrue
createdAt
string

The date and time the user was created

Example2021-08-18T13:48:00+00:00
updatedAt
string

The date and time the user was last modified

Example2021-08-19T18:00:00.000Z
sso
boolean

Whether this account is managed by an Authentication provider or not.

Exampletrue
domain
string | null

The domain this individual is associated with

Exampletenant.learn.link
additionalFields
object | null

Custom field key-value pairs for this user

400

Bad Request — path parameter ref is required

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

The request is invalid

status
number
Example400.0
error
string
ExampleBad Request
message
string
ExampleInvalid JSON on line 1
415

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

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

The request could not be processed due to a validation error

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

Unprocessable Content — validation failed

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

The request could not be processed due to a validation error

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

An unexpected error has occurred

When any default error occurs it may be a system failure and persistent errors may require support.

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

The server is unable to process the request

status
number
Example500.0
error
string
ExampleInternal Server Error

© 2025 Thrive Learning

Website & cookies policy Terms and Conditions Privacy policy