Submits an asynchronous job that creates the given users. Each item takes the same fields as POST /users.
The endpoint responds immediately with 202 Accepted and a jobId; the users are created in the background. Poll GET /users/bulk/{jobId} for progress and per-item results.
Submissions are idempotent: replaying a request with the same Idempotency-Key header returns the existing job instead of creating a duplicate.
A ref that already belongs to a user is reported as a USER_ALREADY_EXISTS per-item failure; no existing user is modified. A ref that belongs to a suspended user reactivates that user, reported as a per-item success with the message User reactivated.
Every item is validated before the job is created, so a batch that holds an invalid item returns 207 and creates no job.
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 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
- Staging:
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
- Staging:
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.
Caller-generated idempotency key for the submission. Generate it once per logical submission and reuse it on retries — replaying the same key returns the existing job instead of creating a duplicate. Requests without the header are rejected with 422.
Create a batch of users
Creates up to 1000 users, each item taking the same fields as POST /users. The required Idempotency-Key header guards against duplicate jobs when the request is retried.
"{\n \"users\": [\n {\n \"ref\": \"UID30084022\",\n \"firstName\": \"Thomas\",\n \"lastName\": \"Jefferson\",\n \"email\": \"thomas.jefferson@thrivelearning.com\",\n \"role\": \"learner\",\n \"jobTitle\": \"Director\",\n \"additionalFields\": {\n \"department\": \"Engineering\"\n }\n },\n {\n \"ref\": \"UID30084023\",\n \"firstName\": \"Abigail\",\n \"lastName\": \"Adams\",\n \"email\": \"abigail.adams@thrivelearning.com\",\n \"loginMethod\": \"email\"\n }\n ]\n}\n"The input to create users in bulk.
The users to create, each taking the same fields as POST /users. Up to 1000 per request. Duplicate refs are collapsed and processed once, the first occurrence winning.
The input to create a new user account.
The email field is required unless loginMethod is set to ref.
Your organisation's unique identifier for this individual
The given name of the individual
The family name of the individual
The email address for the user. Required unless loginMethod is 'ref'.
How the user logs in. Defaults to 'email'.
The role assigned to this individual. Defaults to 'learner' if omitted.
The name of this individual's role in your organisation
Your organisation's unique identifier for this individual's line manager
The date this individual started working with your organisation
The date this individual left your organisation
The user's preferred timezone. If not provided the tenant default is used.
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.
Whether this account is managed by an Authentication provider or not.
The domain this individual is associated with
Custom field key-value pairs matching your configured custom fields.
Accepted — a bulk create job was created (or an existing job was matched by idempotency key). Poll pollUrl for progress and per-item results.
Returned when a bulk job has been accepted for processing.
The id of the job processing the batch
The processing status of a bulk job
The path to poll for progress and per-item results
Multi-Status — some users failed validation, so no job was created. The envelope lists the users that passed validation and the ones that were rejected, so the batch can be corrected and resubmitted.
A multi-status envelope returned when some items in the batch failed validation. No job is created; correct the failed items and resubmit.
The items that passed validation
The number of items that passed validation
The ref of the item, as submitted
The items that failed validation
The number of items that failed validation
The position of the invalid item in the submitted array (refs[2] for suspend and delete, users[2] for create)
The reason the item was rejected. Create items report every rejected field, as field: reason pairs joined with ; .
Unauthorized
Unauthorized
Forbidden
Forbidden
Content Too Large — the request body is above 2 MB. Split the batch and resubmit the parts.
An envelope containing information about the event errors
Unsupported Media Type — Content-Type must be application/json
The request could not be processed due to a validation error
Unprocessable Content — validation failed (missing or empty users, more than 1000 users, a missing or invalid Idempotency-Key header, or no user in the batch passed validation)
The request could not be processed due to a validation error
An unexpected error has occurred
When any default error occurs it may be a system failure and persistent errors may require support.
The server is unable to process the request