Submits an asynchronous job that suspends the users identified by the given refs, marking them as inactive in the organisation.
The endpoint responds immediately with 202 Accepted and a jobId; the suspensions are processed 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.
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.
Suspend a batch of users
Suspends up to 1000 users by ref. The required Idempotency-Key header guards against duplicate jobs when the request is retried.
{
"refs": [
"UID30084022",
"UID30084023",
"UID30084024"
]
}The input to suspend users in bulk.
The refs of the users to suspend. Up to 1000 per request. Duplicate refs are collapsed and processed once.
Accepted — a bulk suspend 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 refs failed validation, so no job was created. The envelope lists the refs 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
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 refs, more than 1000 refs, or no ref 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