API Guide: User Management
An overview of using the R1 Discover APIs (v2) for user management
Introduction
This guide provides detailed instructions for integration partners on how to implement the User Management API endpoints in Version 2 of the R1 Discover API within their applications. By following this guide, partners can seamlessly create and manage users and admins within the R1 Discover platform, ensuring accurate and efficient integration.
Prerequisites
Before starting the integration process, ensure the following:
You have an active R1 Discover Tech Partner account.
You can generate a Bearer token for authentication.
Detailed instructions for setting up your account and generating a token are available here: R1 API: Getting Started (#).
Create User Requirements
When creating a new user in R1 Discover via the V2 API, certain data elements are required, along with an optional shared unique ID. This guide outlines the steps to retrieve these elements to support user creation. If locations, programs, or practitioners remain unchanged, you may not need to repeat all steps for each user created.
Required Fields:
CompanyID: The ID of the company under which the user will be registered.
client_id: A unique identifier from the integration partner system (e.g., "r1-user-123456-01").
Username: A unique username within the R1 Discover system (if left blank, the system may autogenerate one or use the email).
Location: The primary location of the user within the company.
Program: The program to which the user is assigned.
Practitioner: The email address of the practitioner assigned to the user.
Status: Indicates whether the user account is active or inactive (e.g., "active").
Optional Fields:
email: The user’s email address (strongly recommended). If omitted, the system returns a password in the response; otherwise, it emails the password to the user.
initial_password: The initial password for the user account (autogenerated if blank).
company_username: A company-specific username, distinct from the global username, if required. Must be unique within the company (see "Check Company Username" endpoint).
Similar workflows apply to updating users, creating admins (e.g., practitioners), and updating admins.
Workflow Overview
Understanding the sequence of API calls is crucial for efficient user management. This section outlines the recommended order for accessing the User Management endpoints in Version 2 of the R1 Discover API.
Step-by-Step User Management Instructions
1. Generate Bearer Token
Instructions:
Log in to your R1 Discover Tech Partner account.
Navigate to the "My Companies" tab.
Click the "Key" icon to generate a Bearer token.
Copy the token to a secure location. Note: The token will not be visible after you leave the page.
Link to Documentation: Generate Bearer Token (#)
2. Retrieve Company ID
Instructions:
Use the "List Companies" endpoint to retrieve a paginated list of companies and their IDs.
Make a GET request to https://api.r1learning.com/api/v2/companies?page={page}&limit={limit}.
Include the Bearer token in the Authorization header.
Example Request:
GET https://api.r1learning.com/api/v2/companies?page=1&limit=50
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}Link to Documentation: List Companies
3. Validate Locations
Instructions:
Use the "List Company Locations" endpoint to retrieve the list of locations for a specific company.
Make a GET request to https://api.r1learning.com/api/v2/locations/{companyId}?page={page}&limit={limit}.
Replace {companyId} with the company ID from the previous step.
Include the Bearer token in the Authorization header.
Example Request:
GET https://api.r1learning.com/api/v2/locations/12345?page=1&limit=50
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}Link to Documentation: List Company Locations
4. Validate Programs
Instructions:
Use the "List Company Programs" endpoint to retrieve the list of programs for a specific company.
Make a GET request to https://api.r1learning.com/api/v2/programs/{companyId}?page={page}&limit={limit}.
Replace {companyId} with the company ID.
Include the Bearer token in the Authorization header.
Example Request:
GET https://api.r1learning.com/api/v2/programs/12345?page=1&limit=50
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}Link to Documentation: List Company Programs
5. Validate Practitioners
Instructions:
Use the "List Company Admins" endpoint to retrieve the list of practitioners (admins) for a specific company.
Make a GET request to https://api.r1learning.com/api/v2/admins/{companyId}?page={page}&limit={limit}.
Replace {companyId} with the company ID.
Include the Bearer token in the Authorization header.
Example Request:
GET https://api.r1learning.com/api/v2/admins/12345?page=1&limit=50
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}Link to Documentation: List Company Admins
6. Validate Global Username
Instructions:
Use the "Check Global Username" endpoint to verify if a username is available across the R1 Discover system.
Make a GET request to https://api.r1learning.com/api/v2/usernames/check/global/{username}.
Replace {username} with the desired username.
Include the Bearer token in the Authorization header.
** During Create User process, leave username blank to have system auto generate one.
Example Request:
GET https://api.r1learning.com/api/v2/usernames/check/global/johndoe
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}Link to Documentation: Check Global Username
7. Validate Company Username (Optional)
Instructions:
Use the "Check Company Username" endpoint if a company-specific username is required (e.g., for a custom login site). This verifies availability within the company.
Make a GET request to https://api.r1learning.com/api/v2/usernames/check/company/{companyId}/{companyUsername}.
Replace {companyId} with the company ID and {companyUsername} with the desired company-specific username.
Include the Bearer token in the Authorization header.
Example Request:
GET https://api.r1learning.com/api/v2/usernames/check/company/12345/johndoe_company
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}Link to Documentation: Check Company Username
8. Create User
Instructions:
Use the "Create/Update User" endpoint to create a new user.
Make a POST request to https://api.r1learning.com/api/v2/users/{companyId}.
Replace {companyId} with the company ID.
Include the Bearer token in the Authorization header.
Provide the required data in the request body (e.g., client_id, username, client_location, client_program, client_practitioner, client_status).
Example Request:
POST https://api.r1learning.com/api/v2/users/12345
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
Body:
{
"client_id": "r1-user-123456-01",
"username": "johndoe",
"client_email": "[email protected]",
"client_location": "R1 Location 1",
"client_program": "PHP",
"client_practitioner": "[email protected]",
"client_status": "active"
}Link to Documentation: Create/Update User
9. Update User
Instructions:
Use the "Create/Update User" endpoint to update an existing user.
Make a POST request to https://api.r1learning.com/api/v2/users/{companyId}.
Replace {companyId} with the company ID.
Include the Bearer token in the Authorization header.
Provide the updated data in the request body, including the client_id to identify the user.
Example Request:
POST https://api.r1learning.com/api/v2/users/12345
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
Body:
{
"client_id": "r1-user-123456-01",
"username": "johndoe",
"client_email": "[email protected]",
"client_location": "R1 Location 2",
"client_program": "Detox",
"client_practitioner": "[email protected]",
"client_status": "active"
}Link to Documentation: Create/Update User
10. Create Admin
Instructions:
Use the "Create/Update Admin" endpoint to create a new admin (e.g., practitioner).
Make a POST request to https://api.r1learning.com/api/v2/admins/{companyId}.
Replace {companyId} with the company ID.
Include the Bearer token in the Authorization header.
Provide the required data in the request body (e.g., admin_id, admin_email, admin_username, admin_type, admin_location, admin_program, admin_status).
Example Request:
POST https://api.r1learning.com/api/v2/admins/12345
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
Body:
{
"admin_id": "r1-admin-123456-01",
"admin_email": "[email protected]",
"admin_username": "admin123",
"admin_role": "Admin-Read",
"admin_type": "Practitioner",
"admin_location": "R1 Location 1",
"admin_program": "PHP",
"admin_status": "active"
}Link to Documentation: Create/Update Admin
11. Update Admin
Instructions:
Use the "Create/Update Admin" endpoint to update an existing admin.
Make a POST request to https://api.r1learning.com/api/v2/admins/{companyId}.
Replace {companyId} with the company ID.
Include the Bearer token in the Authorization header.
Provide the updated data in the request body, including the admin_id to identify the admin.
Example Request:
POST https://api.r1learning.com/api/v2/admins/12345
Headers:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
Body:
{
"admin_id": "r1-admin-123456-01",
"admin_email": "[email protected]",
"admin_username": "admin123",
"admin_role": "Admin",
"admin_type": "Practitioner",
"admin_location": "R1 Location 2",
"admin_program": "Detox",
"admin_status": "active"
}Link to Documentation: Create/Update Admin
Notes
Authentication: All requests require a valid Bearer token in the Authorization header to avoid 401 Unauthenticated errors.
Pagination: For GET requests (e.g., "List Companies"), use page and limit query parameters to manage large datasets (default: 50, max: 100).
Error Handling: Handle common errors such as 401 (Unauthenticated), 403 (Unauthorized), and 404 (Not Found). Refer to individual endpoint documentation for details.
Username Validation: Always validate usernames (global and company-specific) to ensure uniqueness before creating users or admins.
Reusability: Cache location, program, and practitioner data if they remain static to reduce redundant API calls.
For additional resources, explore the R1 Discover API Postman Collection or contact support at [email protected].
Last updated