Product Guide

Set Up Users via API

Suggest Edits

As a Builder Admin, you can use Zus Auth Service APIs to manage two types of accounts within your Builder Org on Zus: users and app clients.

A "user" on Zus is a human who has a name, email address, and credentials to verify their identity as an individual. Users can access Zus APIs and UIs with their credentials.

If you have clinical users, Zus allows you to optionally create a FHIR Practitioner resource for your users and link this Practitioner resource to their identity. You can then associate that FHIR Practitioner resource with FHIR Care Teams and PractitionerRoles.

If you have patient users that require access to Zus, you'll want to create Patient resources and link them to their user identities.

You can also manage your users with our user management admin page.

Setting up a New User in your Organization

Follow the steps below in sequence to set up a new user. NOTE: The easiest way to do this in practice is with the User Creation Guide in our Zus Health Postman Collection, which automates these steps and allows you to create multiple users with one click.

Step 1: Create a Practitioner Resource (Optional)

This can be a minimal resource that just contains your user's first and last names. This call will return a practitioner_id that you should retain. Once created, this Practitioner is available for PractitionerRole assignment and CareTeam linking.

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

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

Step 2: Create a User in the Auth Service

Step 2a: Specify the role you want the user to have. Your current role options are Builder Admin and Care Team User. Set the RoleName variable's current value to either Builder Admin or Care Team User.

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

{
    "data": [
        {
            "type": "auth/roles",
            "id": "<UUID>", #RoleID used in step 2b
            "attributes": {
                "createdAt": 1638828368,
                "description": "",
                "isManaged": true,
                "name": "Care Team User",
                "permissions": [
                    ....
                ],
                "updatedAt": 1655996421
            }
        }
    ],
    "links": {
        "next": "https://api.sandbox.zusapi.com/auth/roles?filter[name]=Care%20Team%20User&page[count]=50&page[offset]=50",
        "self": "https://api.sandbox.zusapi.com/auth/roles?filter[name]=Care%20Team%20User&page[count]=50&page[offset]=0"
    }
}

Step 2b: Create a user with the role from step 2a. To ensure the user can eventually log in with single sign-on (SSO) if you establish an SSO connection with Zus, the user email with their identity provider must match the email used when creating the user's Zus account below.

Optional fields:

  • Set clientId to the value in the body below so that users are redirected to this documentation website upon resetting their passwords.
  • Set sendPasswordResetEmail to false so that the user does NOT receive an email to reset their password. This istrue by default.

📘

New users to Zus’s sandbox environment will receive a welcome email with links to our apps and documentation to help them get started in the sandbox. New users in the production environment will not receive a welcome email.

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

{
    "data": {
        "type": "auth/users",
        "attributes": {
            "email": "{{Email}}",
            "name": "{{Username}}",
            "userType": "builder",
            "clientId": "PuzaR6b4U1l2wMC3qciU1qUJI2fOxJLw", #Optional, redirects user to Zus documentation upon resetting their password
            "sendPasswordResetEmail": true, #Optional boolean (true by default)
        },
        "relationships": {
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "{{RoleID}}" #from step 2a
                }
            },
            "fhir/practitioner": {
                "data": {
                    "type": "fhir/practitioner", 
                    "id": "{{OptionalPractitionerID}}" #from step 1
                }
            }
        }
    }
}

Managing Practitioner and Patient Users

Overview

If you have users that need to be linked to corresponding FHIR Practitioner or Patient resources, you can use our Practitioner or Patient User Upsert APIs to do so. For example, a clinical user can be linked to a Practitioner resource so that patient data they create or update can be tied back to their practitioner. You can use the Practitioner User Upsert API endpoint to create & update users, create & update Practitioner resources, and link the two together.

Practitioner User Upsert API

The Practitioner User Upsert endpoint performs upsert operations on a FHIR Practitioner resource and the user linked to that Practitioner resource in the same API call, allowing them to stay in sync as you make updates over time.

This endpoint is intended for the following use cases:

  • Initial simultaneous creation of BOTH new Practitioner resources and users
  • Simultaneous PUT updates to BOTH Practitioner resources and users, ensuring Practitioner resources and the users they are linked to stay in sync

To make changes to only the Practitioner resource or only the user, use the appropriate PUT or PATCH endpoints:

Practitioner User Upsert API Specification

PUT https://api.sandbox.zusapi.com/auth/practitioner/$upsert
NOTE: All attributes are required

{
	"data": {
		"attributes": {
			"practitionerIdentiferSystem": "<fhir identifier system>",
			"practitioner": {... the fhir/practitioner data },
			"user": {... the auth service user data}
		}
	}
}

The request body must have the following data points or the request will return an error:

  • attributes.practitionerIdentifierSystem this is the identifier system used to look up the Practitioner resource to check if it already exists before updating it or create a new resource.
  • attributes.practitioner request field must contain a Practitioner identifier object that includes the practitionerIdentifierSystem above, because this specific identifier & system combination is used to look up the Practitioner resource.
  • attributes.user must have userType set to "builder."

Example Request Body:

{
    "data": {
        "attributes": {
            "practitionerIdentifierSystem": "http://hospital.smarthealthit.org",
            "practitioner": {
                "resourceType": "Practitioner",
                "text": {
                    "status": "generated",
                    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n      <p>Dr Adam Careful is a Referring Practitioner for Acme Hospital from 1-Jan 2012 to 31-Mar\n        2012</p>\n    </div>"
                },
                "identifier": [
                    {
                        "use": "official",
                        "system": "http://hospital.smarthealthit.org",
                        "value": "991032702992299"
                    }
                ],
                "active": true,
                "name": [
                    {
                        "family": "Flubegone",
                        "given": [
                            "Debra"
                        ],
                        "prefix": [
                            "Dr"
                        ]
                    }
                ],
                "address": [
                    {
                        "use": "home",
                        "line": [
                            "534 Erewhon St"
                        ],
                        "city": "PleasantVille",
                        "state": "Vic",
                        "postalCode": "3999"
                    }
                ],
                "qualification": [
                    {
                        "identifier": [
                            {
                                "system": "http://example.org/UniversityIdentifier",
                                "value": "12345"
                            }
                        ],
                        "code": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v2-0360/2.7",
                                    "code": "BS",
                                    "display": "Bachelor of Science"
                                }
                            ],
                            "text": "Bachelor of Science"
                        },
                        "period": {
                            "start": "1995"
                        },
                        "issuer": {
                            "display": "Example University"
                        }
                    }
                ]
            },
            "user": {
                "data": {
                    "type": "auth/users",
                    "attributes": {
                        "email": "[email protected]",
                        "name": "Debra Flubegone M.D.",
                        "userType": "builder",
                        "sendPasswordResetEmail": false
                    },
                    "relationships": {
                        "auth/roles": {
                            "data": {
                                "type": "auth/roles",
                                "id": "{{RoleID}}"
                            }
                        }
                    }
                }
            }
        }
    }
}

You can see a sample API call and request body in the Zus Health Workspace in Postman: Zus Health API>Auth & Permissions>Auth Service API>User>Upsert Practitioner User.

Example Success Response:

  • Code = 201 if a new Practitioner OR user was created, 200 if no new resources were created.
  • Body = the user (which has the Practitioner resource ID on it)
{
    "data": {
        "type": "auth/users",
        "id": "3d81a0ca-3e72-429d-9459-ed43d83802d9",
        "attributes": {
            "createdAt": 1670597992,
            "email": "[email protected]",
            "name": "Debra Flubegone M.D.",
            "updatedAt": 1670597992,
            "userType": "builder"
        },
        "relationships": {
            "auth/builders": {
                "data": {
                    "type": "auth/builders",
                    "id": "c1e40956-7808-4063-9f43-49370f3c8ddb"
                }
            },
            "auth/roles": {
                "data": {
                    "type": "auth/roles",
                    "id": "23b56d6c-eb02-426f-9034-a8a90a599ca3"
                }
            },
            "fhir/practitioner": {
                "data": {
                    "type": "fhir/practitioner",
                    "id": "19c21c89-c0c4-49d6-9aa3-f88228d3a9f4" #FHIR Practitioner resource ID from the Practitioner resource upsert operation
                }
            }
        }
    }
}

Example Failure Responses:
The code/body from the FHIR request or user request that failed.

FHIR 412 error:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "HAPI-0988: Failed to UPDATE resource with match URL \"Practitioner?identifier=https://zusapi.com/sarahs-test-identifier|1234\" because this search matched 2 resources"
        }
    ]
}

Auth Service 400 error:

[
    {
        "id": "70ac9e1a-3718-4e68-8de2-b735e6cb9bd7",
        "detail": "a user must have a user type"
    }
]

Logical flow

Patient User Upsert API

Like for Practitioner users, the Patient User Upsert endpoint performs upsert operations on a Patient resource and the user linked to that patient resource in the same API call, allowing them to stay in sync as you make updates over time.

This endpoint is intended for the following use cases:

  • Initial simultaneous creation of BOTH new Patient resources and users
  • Simultaneous PUT updates to BOTH Patient resources and users, ensuring Patient resources and their linked users stay in sync (e.g., updating email on the Patient resource and on the user)

To make changes to only the Patient resource or only the user, use the appropriate PUT or PATCH endpoints:

Patient User Upsert API Specification

PUT https://api.sandbox.zusapi.com/auth/patient/$upsert
NOTE: All attributes are required

{
	"data": {
		"attributes": {
			"patientIdentiferSystem":"<fhir identifier system>",
			"patient": {... the fhir/patient data },
			"user": {... the auth service user data}
		}
	}
}

The request body must have the following data points or the request will return an error:

  • attributes.patientIdentifierSystem - this is the identifier system used to look up the Patient resource to check if it already exists before updating it or create a new resource.
  • attributes.patient request field must contain a Patient identifier object that includes the patientIdentifierSystem above, because this specific identifier & system combination is used to look up the Patient resource.
  • attributes.user must have userType set to "individual." This ensures the user only sees data linked to their corresponding Patient resource.

Example Request Body:

{
    "data": {
        "attributes": {
            "patientIdentifierSystem": "http://hospital.smarthealthit.org",
            "patient": {
                "resourceType": "Patient",
                "name": [
                    {
                        "family": "Smith",
                        "given": [
                            "Mike"
                        ]
                    }
                ],
                "telecom": [
                    {
                        "system": "phone",
                        "value": "(999) 999-9999"
                    },
                    {
                        "system": "email",
                        "value": "[email protected]"
                    }
                ],
                "gender": "male",
                "birthDate": "1970-01-01",
                "address": [
                    {
                        "line": [
                            "101 Walnut St"
                        ],
                        "city": "Watertown",
                        "state": "MA",
                        "postalCode": "02472",
                        "country": "US"
                    }
                ],
                "communication": [
                    {
                        "language": {
                            "coding": [
                                {
                                    "system": "urn:ietf:bcp:47",
                                    "code": "en-US",
                                    "display": "English"
                                }
                            ],
                            "text": "English"
                        },
                        "preferred": true
                    }
                ],
                "identifier": [
                    {
                        "use": "usual",
                        "type": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                    "code": "MR",
                                    "display": "Medical Record Number"
                                }
                            ],
                            "text": "Medical Record Number"
                        },
                        "system": "http://hospital.smarthealthit.org",
                        "value": "1032702"
                    }
                ]
            },
            "user": {
                "data": {
                    "type": "auth/users",
                    "attributes": {
                        "email": "[email protected]",
                        "name": "John Smith",
                        "userType": "individual",
                        "sendPasswordResetEmail": false
                    },
                    "relationships": {
                        "auth/roles": {
                            "data": {
                                "type": "auth/roles",
                                "id": "{{RoleID}}"
                            }
                        }
                    }
                }
            }
        }
    }
}

You can see a sample API call and request body in the Zus Health Workspace in Postman: Zus Health API>Auth & Permissions>Auth Service API>User>Upsert Patient User.

Example Success Response:

  • Code = 201 if a new Patient OR user was created, 200 if no new resources were created.
  • Body = the user (which has the Patient resource ID on it)
{
  "data": {
    "type": "auth/users",
    "id:": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "attributes": {
      "createdAt": 0,
      "updatedAt": 0,
      "name": "string",
      "email": "string",
      "userType": "string"
    },
    "relationships": {
      "auth/roles": {
        "data": {
          "type": "auth/roles",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      },
      "fhir/Patient": {
        "data": {
          "type": "fhir/Patient",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" #FHIR Patient resource ID from the Patient resource upsert operation
        }
      }
    }
  }
}

Example Failure Responses:
The code/body from the FHIR request or user request that failed

FHIR 412 error:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "HAPI-0988: Failed to UPDATE resource with match URL \"Patient?identifier=https://zusapi.com/sarahs-test-identifier|1234\" because this search matched 2 resources"
        }
    ]
}

Auth Service 400 error:

[
    {
        "id": "70ac9e1a-3718-4e68-8de2-b735e6cb9bd7",
        "detail": "a user must have a user type"
    }
]

Logical flow

Updated 6 months ago