Who is this article for?

Administrators who want to learn to create users via the API.

Administrator permissions are required.

This article explains how to create users in Disclose using the POST /api/v1/users endpoint.

Understanding the endpoint

The endpoint requires an Authorization: Bearer {accessToken} header and the Tenant Administrator role.

Use the following endpoint to create users:

POST /api/v1/users

Structuring the request

The request body must include a users array with user objects. Here is an example:

{
  "users": [
    {
      "syncId": "a.smith@testnet.com",
      "firstName": "Alex",
      "lastName": "Smith",
      "otherNames": null,
      "email": "a.smith@testnet.com",
      "sso": true,
      "role": "Tenant User|User Administrator",
      "groups": "Your Review Group",
      "licences": "UK Disclose Checklists",
      "primaryGroup": null
    }
  ]
}

The following table describes each field:

Interpreting the success response

A HTTP 200 status means the batch was processed. Check each row's action field to confirm the outcome.

Here is an example response:

{
  "tenantId": 1,
  "saved": 2,
  "results": [
    {
      "syncId": "a.smith@testnet.com",
      "email": "a.smith@testnet.com",
      "userId": 41,
      "action": "Added",
      "message": "Created user successfully",
      "warnings": [
        "Could not find user group: Your Review Group",
        "Could not find licence: UK Disclose Checklists",
        "Created user successfully, however, failed to send email"
      ]
    }
  ]
}

The following table describes the response fields:

Note: Warnings do not fail the user. An unknown group, licence, role, or primary group, and "no licences available", are all warnings — the user is still saved.