Creating Users

As a Builder Admin, you can create and manage users in your Builder Org through the Zus App or the Zus Auth Service API.

A user on Zus is a human with a name, email address, and credentials that verify their identity. Users sign in to access Zus APIs and UIs. (To create non-human accounts, see App Clients.)

📘

Which method should I use?

• Use the Zus App for one-off user management — adding teammates, editing details, etc.
• Use the API when you need to automate user provisioning, integrate with your own onboarding flow, or link users to FHIR Practitioner resources at creation.

Creating users in the Zus App

In the Zus App, go to Admin Settings → Users to view, add, or edit users.

Requirements and limitations:

• Only Builder Admin users can create new users.
• Users cannot currently be deleted from this page.

Creating users via API

Creating a user via the API takes two main steps (plus one optional step for clinical users):

1. (Optional) Create a FHIR Practitioner resource — for clinical users only.
2. Look up the role ID you want to assign.
3. Create the user with that role (and optionally link the Practitioner).

📘

For a runnable walkthrough, see the User Creation Guide in the Zus Health Postman Collection.

Step 1 (Optional): Create a FHIR Practitioner resource

Skip this step unless you're creating a clinical user.

For clinical users, you can create a FHIR Practitioner resource and link it to the user's identity. Once linked, the Practitioner can be assigned to FHIR Care Teams and PractitionerRoles.

A minimal Practitioner — just first and last name — is enough. Save the practitioner_id returned by this call; you'll use it in Step 3.

Request

POST https://api.sandbox.zusapi.com/fhir/Practitioner

{
  "resourceType": "Practitioner",
  "active": true,
  "name": [
    {
      "family": "{{FamilyName}}",
      "given": ["{{GivenName}}"]
    }
  ]
}

Step 2: Look up the role ID

Each user is assigned exactly one role. The available roles are:

Set the RoleName variable to either Builder Admin or Care Team User, then make this request to fetch its ID:

Request

GET https://api.sandbox.zusapi.com/auth/roles?filter[name]={{RoleName}}

Response (abbreviated)

{
  "data": [
    {
      "type": "auth/roles",
      "id": "<UUID>",
      "attributes": {
        "name": "Care Team User",
        "description": "",
        "isManaged": true,
        "permissions": ["..."],
        "createdAt": 1638828368,
        "updatedAt": 1655996421
      }
    }
  ]
}

Copy the id value — you'll pass it as RoleID in Step 3.

Step 3: Create the user

This call creates the user account, assigns the role from Step 2, and optionally links the Practitioner from Step 1.

Request

POST https://api.sandbox.zusapi.com/auth/users

{
  "data": {
    "type": "auth/users",
    "attributes": {
      "email": "{{Email}}",
      "name": "{{Username}}",
      "userType": "builder",
      "clientId": "PuzaR6b4U1l2wMC3qciU1qUJI2fOxJLw",
      "sendPasswordResetEmail": true
    },
    "relationships": {
      "auth/roles": {
        "data": {
          "type": "auth/roles",
          "id": "{{RoleID}}"
        }
      },
      "fhir/practitioner": {
        "data": {
          "type": "fhir/practitioner",
          "id": "{{OptionalPractitionerID}}"
        }
      }
    }
  }
}

Field reference

What happens after the user is created

• Sandbox environment: New users receive a welcome email with links to Zus apps and documentation.
• Production environment: No welcome email is sent.
• If sendPasswordResetEmail is true (the default), the user also gets a password-reset email so they can set their initial password.