Suspend users in bulk

  • Updated on Oct 9, 2026
  • Published on Aug 13, 2026
Prev Next
Post
/users/bulk/suspend

Submits an asynchronous job that suspends the users identified by the given refs or ids, marking them as inactive in the organisation.

A batch names its users by one identifier kind: send refs or ids, not both. A body with both arrays is rejected with 400; a body with neither is rejected with 422.

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.

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
Header parameters
Idempotency-Key
stringRequired

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.

Body parameters
bulkSuspendUsersByRef

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"
  ]
}
bulkSuspendUsersById

Suspend a batch of users by id

Suspends up to 1000 users by user id. Send ids instead of refs; the two arrays cannot be combined.

{
  "ids": [
    "6143eedfd39243e830bdbb8c",
    "6143eedfd39243e830bdbb8d",
    "6143eedfd39243e830bdbb8e"
  ]
}
object

The input to suspend users in bulk. Names the users with refs or with ids, never both.

refs
Array of string

The refs of the users to suspend. Up to 1000 per request. Duplicate refs are collapsed and processed once. Cannot be combined with ids.

Min items1
Max items1000
Example[ "UID30084022", "UID30084023" ]
string
ids
Array of string

The ids of the users to suspend, as 24-character hexadecimal ObjectIds. Up to 1000 per request. Duplicate ids are collapsed and processed once; an id that is not a valid ObjectId is rejected per item. Cannot be combined with refs.

Min items1
Max items1000
Example[ "6143eedfd39243e830bdbb8c", "6143eedfd39243e830bdbb8d" ]
string
OneOf
object
object
refs
Array of string Required

The refs of the users to suspend. Up to 1000 per request. Duplicate refs are collapsed and processed once. Cannot be combined with ids.

Min items1
Max items1000
Example[ "UID30084022", "UID30084023" ]
string
ids
Array of string

The ids of the users to suspend, as 24-character hexadecimal ObjectIds. Up to 1000 per request. Duplicate ids are collapsed and processed once; an id that is not a valid ObjectId is rejected per item. Cannot be combined with refs.

Min items1
Max items1000
Example[ "6143eedfd39243e830bdbb8c", "6143eedfd39243e830bdbb8d" ]
string
object
object
refs
Array of string

The refs of the users to suspend. Up to 1000 per request. Duplicate refs are collapsed and processed once. Cannot be combined with ids.

Min items1
Max items1000
Example[ "UID30084022", "UID30084023" ]
string
ids
Array of string Required

The ids of the users to suspend, as 24-character hexadecimal ObjectIds. Up to 1000 per request. Duplicate ids are collapsed and processed once; an id that is not a valid ObjectId is rejected per item. Cannot be combined with refs.

Min items1
Max items1000
Example[ "6143eedfd39243e830bdbb8c", "6143eedfd39243e830bdbb8d" ]
string
Responses
202

Accepted — a bulk suspend job was created (or an existing job was matched by idempotency key). Poll pollUrl for progress and per-item results.

object

Returned when a bulk job has been accepted for processing.

jobId
string

The id of the job processing the batch

Example6863f9a2c1d2e3f4a5b6c7d8
status
string

The processing status of a bulk job

Valid values[ "pending", "processing", "completed", "failed" ]
Exampleprocessing
pollUrl
string

The path to poll for progress and per-item results

Example/rest/v2/users/bulk/6863f9a2c1d2e3f4a5b6c7d8
207

Multi-Status — some entries failed validation, so no job was created. The envelope lists the entries that passed validation and the ones that were rejected, so the batch can be corrected and resubmitted.

Expand All
object

A multi-status envelope returned when some items in the batch failed validation. No job is created; correct the failed items and resubmit.

success
object

The items that passed validation

count
number

The number of items that passed validation

Example2
entities
Array of object
object
reference
string

The identifier of the item in its normalised form: the ref with surrounding spaces removed, or the id in lowercase hex for an ids batch. Match it to your request after the same normalisation

ExampleUID30084022
failure
object

The items that failed validation

count
number

The number of items that failed validation

Example1
entities
Array of object
object
reference
string

The position of the invalid item in the submitted array (refs[2] or ids[2] for suspend and delete, users[2] for create)

Examplerefs[2]
message
string

The reason the item was rejected. Create items report every rejected field, as field: reason pairs joined with ; .

Examplecannot be empty
400

Bad Request — the body carries both refs and ids. A batch names its users by one identifier kind only; send one array or the other.

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 is invalid

status
number
Example400
error
string
ExampleBad Request
message
string
ExampleInvalid JSON on line 1
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
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 — validation failed (neither refs nor ids present, an empty array, more than 1000 entries, a missing or invalid Idempotency-Key header, or no entry in the batch passed validation)

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
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
id
string
ExampleUNIQUEREFERENCE111000
timestamp
string
Example2020-03-09T22:18:26.625Z
eventType
string
Valid values[ "user_joined", "user_updated", "user_suspended" ]
message
object

The server is unable to process the request

status
number
Example500
error
string
ExampleInternal Server Error

© 2025 Thrive Learning

Website & cookies policy Terms and Conditions Privacy policy