You can 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.

Requirements

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": "joe.bloggs@example.com",
  "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"
        }
      ]
    }
  ]
}

📘
Seat availability and billing
This feature is currently in Early Access. If your organization is enrolled, SafetyCulture automatically purchases additional paid seats when your seat limit is reached during user provisioning.

Users are provisioned with the correct seat type.

Your billing admin receives a summary email for any paid seats purchased automatically.

Your next invoice will include a prorated charge for the seats purchased from the date they were added.

Monitor your seat allocation regularly in the SafetyCulture web app to stay on top of your subscription. Contact your customer success manager if you have any questions.

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.