API Guide: User Management

An overview of using the R1 Discover APIs for user management.

Introduction

This guide provides detailed instructions for integration partners on how to effectively implement the User Management API endpoints within their applications. By following this guide, partners can ensure a seamless integration process, enabling them to create and manage users within the R1 Discover platform.

Prerequisites

Before beginning the integration process, ensure an R1 Discover Tech Partner account has been created, and you are able to generate your bearer token for authentication.

Detailed instructions on prerequisites can be found here: R1 API: Getting Started

Create User Requirements

When creating a new user in R1 Discover via the API, it is required to include a handful of data elements in addition to a shared unique ID. This guide details the steps to retrieve those elements in support of creating users. As long as locations, programs, practitioners do not change, it may not be require to repeat all steps for each created user.

1. CompanyID: the ID of the company under which the user will be registered

2. client_ID: A unique identifier from the integration partner system.

3. Username: A unique username within the R1 Discover system

4. Location: The primary location of the user within the company.

5. Program: The program to which the user is assigned.

6. Practitioner: The email address of the practitioner aligned to the user.

7. Status: Indicates whether the user account is active or inactive.

These fields can optionally be included:

1. email: The email address of the user, STRONGLY RECOMMENDED, but not required. System will return a password in the response if an email is not included, otherwise the password will be emailed to the new user.

2. initial_password: The initial password for the user account. System will auto-generate if left blank.

3. company_usename: A specific username tied to the company, if different from the general username. If a company wants their users to a have specific username. Must be unique within the company account, see Check Company Username Availability endpoint.

Similar workflows can be followed to update users, create admins (practitioners), and update admins.

Workflow Overview

Understanding the workflow of accessing the User Management API endpoints is crucial for efficient integration. This section outlines the order in which the endpoints should be accessed to successfully create and manage users.

• Generate Bearer Token

• Retrieve Company ID

• Validate Locations

• Validate Programs

• Validate Practitioners

• Validate Global Username

• Validate Company Username (Optional)

• Create User

• Update User

• Create Admin

• Update Admin

Step-by-Step User Management Instructions

Generate Bearer Token

Instructions:

1. Log into R1 Discover Tech Partner Account.

2. Select the My Companies tab.

3. Click the Key icon to generate a token.

4. Copy the token to a secure location. Note that the token will no longer be visible once you leave the page.

Link to Token Generation Documentation: Generate Bearer Token

Retrieve Company ID

Instructions:

1. Use the Company List Endpoint to retrieve the list of companies and their IDs.

2. Make a GET request to https://api.r1learning.com/api/v1/company-list/{page}/{limit}.

3. Include the Bearer token in the request headers.

Link to Documentation: Company List Endpoint

Validate Locations

Instructions:

1. Use the View Company Locations Endpoint to retrieve the list of locations for the company.

2. Make a GET request to https://api.r1learning.com/api/v1/view-company-locations/{companyId}/{page}/{limit}.

3. Include the Bearer token in the request headers.

Link to Documentation: View Company Locations Endpoint

Validate Programs

Instructions:

1. Use the View Company Programs Endpoint to retrieve the list of programs for the company.

2. Make a GET request to https://api.r1learning.com/api/v1/view-company-programs/{companyId}/{page}/{limit}.

3. Include the Bearer token in the request headers.

Link to Documentation: View Company Programs Endpoint

Validate Practitioners

Instructions:

1. Use the View Company Practitioners Endpoint to retrieve the list of practitioners for the company.

2. Make a GET request to https://api.r1learning.com/api/v1/view-company-practitioners/{companyId}/{page}/{limit}.

3. Include the Bearer token in the request headers.

Link to Documentation: View Company Practitioners Endpoint

Validate Username

Instructions:

1. Use the Check Global Username Availability to validate the username is available.

2. Make a GET request to https://api.r1learning.com/api/v1/users/check-username/global/{username}.

3. Include the Bearer token in the request headers.

Link to Documentation: Check Global Username Availability

Validate Company Username (Optional)

This is only used if client has requested a company specific login site and credentials for their users.

Instructions:

1. Use the Check Company Username Availability to validate the username is available.

2. Make a GET request to https://api.r1learning.comapi/v1/users/check-username/company/{companyId}/{companyUsername}.

3. Include the Bearer token in the request headers.

Link to Documentation: Check Company Username Availability

Create User

Instructions:

1. Use the Create User Endpoint to create a new user.

2. Make a POST request to https://api.r1learning.com/api/v1/companies/{companyId}/users.

3. Include the Bearer token in the request headers.

4. Provide the required data: Company ID, Shared User ID, Username, Location, Program, Practitioner, Status.

Link to Documentation: Create User Endpoint

Update User

Instructions:

1. Use the Update User Endpoint to update an existing user.

2. Make a PUT request to https://api.r1learning.com/api/v1/companies/{companyId}/users/{clientId}.

3. Include the Bearer token in the request headers.

4. Provide the updated data: Company ID, Shared User ID, Username, Email, Location, Program, Practitioner, Status.

Link to Documentation: Update User Endpoint

Create Admin

Instructions:

1. Use the Create Admin Endpoint to create a new admin.

2. Make a POST request to https://api.r1learning.com/api/v1/companies/{companyId}/admins.

3. Include the Bearer token in the request headers.

4. Provide the required data: Company ID, Shared Admin ID, Username, email, type, Location, Program, Status.

Link to Documentation: Create Admin Endpoint

Update Admin

Instructions:

1. Use the Update Admin Endpoint to update an existing user.

2. Make a PUT request to https://api.r1learning.com/api/v1/companies/{companyId}/admins/{adminId}.

3. Include the Bearer token in the request headers.

4. Provide the updated data: Company ID, Shared Admin ID, Username, Email, Type, Location, Program, Status.

Link to Documentation: Update Admin Endpoint