Create a user

  • Published on May 21, 2026
  • 4 minute(s) read
Prev Next
Post
/users

Creates a new user account in the organisation. The ref field is your organisation's unique identifier for the individual and must be unique.

The email field is required unless loginMethod is set to ref.

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
Body parameters
createUser

Create a new user

Creates a new user account with all common fields. The email field is required when loginMethod is 'email' (the default).

"{\n  \"ref\": \"UID30084022\",\n  \"firstName\": \"Thomas\",\n  \"lastName\": \"Jefferson\",\n  \"email\": \"user@thrivelearning.com\",\n  \"loginMethod\": \"email\",\n  \"role\": \"learner\",\n  \"jobTitle\": \"Director\",\n  \"managerRef\": \"UID0034234555\",\n  \"startDate\": \"2021-01-01T09:00:00+00:00\",\n  \"timeZone\": \"Europe/London\",\n  \"languageCode\": \"en\",\n  \"sso\": false,\n  \"domain\": \"tenant.learn.link\",\n  \"additionalFields\": {\n    \"department\": \"Engineering\",\n    \"costCentre\": \"CC-001\"\n  }\n}\n"
Expand All
object

The input to create a new user account.

The email field is required unless loginMethod is set to ref.

ref
string Required

Your organisation's unique identifier for this individual

Max length500
ExampleUID30084022
firstName
string Required

The given name of the individual

Max length255
ExampleThomas
lastName
string Required

The family name of the individual

Max length255
ExampleJefferson
email
string (email)

The email address for the user. Required unless loginMethod is 'ref'.

Max length320
Exampleuser@thrivelearning.com
loginMethod
string

How the user logs in. Defaults to 'email'.

Valid values[ "email", "ref" ]
Default"email"
Exampleemail
role
string

The role assigned to this individual. Defaults to 'learner' if omitted.

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

The name of this individual's role in your organisation

Max length500
ExampleDirector
managerRef
string

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

Max length500
ExampleUID0034234555
startDate
string (date-time)

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. If not provided the tenant default is used.

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

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