Bulk user operations

📘
Bulk user management APIs are in Early Access, and may change without notice.

Requirements

Create and update users in bulk through two separate flows:

Synchronous: Create or update up to 10 users per request with immediate results, including the created user IDs.
Asynchronous: Manage large-scale user creation or update through a background job process.

Both flows support the same operations and API format. If the system encounters an error with a user record, it will continue processing the remaining records.

API format

{
  "username": "[email protected]",
  "first_name": "Joe",
  "last_name": "Bloggs",
  "password": "[REDACTED]",
  "seat_type": "SUBSCRIPTION_SEAT_TYPE_PREMIUM",
  "timezone": "Australia/Sydney",
  "status": "USER_ACTIVE_STATUS_ACTIVE",
  "language": "LANGUAGE_EN_US",
  "permission_set": {
    "name": "Administrator"
  },
  "groups": {
    "remove_references": [
      { "name": "*" }
    ],
    "add_references": [
      { "name": "My Group" },
      { "name": "Another Group" },
      { "id": "87b859dc-e616-40a3-939a-08c20969b105" }
    ]
  },
  "sites": {
    "remove_references": [
      { "name": "*" }
    ],
    "add_references": [
      { "name": "Sydney" }
    ]
  },
  "attributes": [
    {
      "reference": {
        "name": "Department"
      },
      "values": [
        {
          "string_value": "Management"
        }
      ]
    }
  ]
}

Synchronous

Use the Create or update users synchronously endpoint for immediate bulk operations.

You can send up to 10 users per request, and the rate limit is 5 requests per minute. For larger operations, use the asynchronous endpoint.

Asynchronous

Use the following endpoints to manage larger user updates through a job-based flow:

Step 1: Initialize the job

Start by calling Initialize create-or-update users job to create a job. This returns a job_id that you'll use to add users and later start the job.

You can add up to 2000 users per request. To process more users, call the same endpoint again with the job_id and additional users.

Step 2: Start the job

After initializing the job, call the Start create-or-update users job endpoint to begin processing.

Use the validate_only parameter to validate records without making changes.

Step 3: Check validation results and progress

Use Get create or update users job to track the job's status and review validation results.

This includes progress updates and detailed validation information when validate_only is set to false.