User Management
An overview of the User Management collection of endpoints.
Overview of User Management
The User Management category in the R1 Discover API provides a comprehensive set of endpoints designed to manage users and administrators within a company. These endpoints allow you to create, update, and retrieve detailed information about users and admins, including their roles, statuses, and associations with specific locations or programs. Additionally, this category includes utilities for checking username availability and updating unique identifiers, ensuring seamless user management across the platform.
This category is particularly useful for administrators or developers who need to programmatically manage user accounts, assign roles, and ensure proper access control within the R1 Discover ecosystem.
Endpoints in This Category
The "User Management" collection includes the following endpoints:
List Company Users Retrieve a paginated list of users associated with a specific company or across all companies, including details such as email, status, location, and program.
Create/Update User (upsert) Create a new user for a company or update an existing user’s details, such as their email, location, program, or status.
List Company Admins Fetch a list of administrators associated with a specific company or across all companies, including their roles, default locations, and programs.
Create/Update Admin (upsert) Create a new admin for a company or update an existing admin’s details, such as their role, type, location, or status.
List Admin Roles Retrieve a list of available admin roles, including their names and descriptions, to understand the permissions associated with each role.
Update Admin/User Unique ID Update the unique identifier for a user or admin, ensuring proper integration with external systems.
Check Global Username Check the availability of a global username across the entire platform.
Check Company Username Check the availability of a company-specific username within a given company.
Each endpoint in this category requires authentication via a Bearer token, which must be included in the Authorization header of your requests. For more details on authentication, refer to the Authentication Guide.
Use Cases
The User Management endpoints are typically used in the following scenarios:
User Onboarding: Use the Create/Update User endpoint to onboard new users into a company, assigning them to specific locations or programs.
Admin Management: Leverage the Create/Update Admin and List Company Admins endpoints to manage administrators, ensuring proper access control and role assignments.
Role Configuration: Use the List Admin Roles endpoint to understand available admin roles and their permissions, then assign appropriate roles using the Create/Update Admin endpoint.
Username Validation: Utilize the Check Global Username and Check Company Username endpoints to validate usernames before creating or updating users or admins, avoiding conflicts.
External System Integration: Use the Update Admin/User Unique ID endpoint to align R1 Discover user IDs with those in external systems, ensuring seamless data synchronization.
User Tracking: Retrieve user and admin data with the List Company Users and List Company Admins endpoints to monitor activity, status, or last activity dates.
Best Practices
Authentication: Always include a valid Bearer token in the Authorization header to avoid 401 Unauthenticated errors.
Pagination: Endpoints like List Company Users and List Company Admins support pagination parameters (page and limit). Use these to manage large datasets efficiently and avoid performance issues.
Filtering Options: Utilize query parameters like maxDays, userStatus, location_id, and program_id in List Company Users and List Company Admins to filter results and retrieve only the data you need.
Error Handling: Be prepared to handle common errors such as 401 Unauthenticated, 403 Unauthorized, 404 Not Found (e.g., user/admin not found), and validation errors. Refer to the individual endpoint documentation for detailed error responses.
Data Validation: When using Create/Update User or Create/Update Admin, ensure that required fields (e.g., username, client_email, admin_role) are provided and conform to expected formats to avoid validation errors.
Username Checks: Always validate usernames using the Check Global Username and Check Company Username endpoints before creating or updating users/admins to prevent conflicts.
Role Assignment: Use the List Admin Roles endpoint to ensure that the admin_role provided in Create/Update Admin corresponds to a valid role.
Integration Points
To effectively use the User Management endpoints, ensure your application is properly authenticated. You will need to:
Obtain an API Token: Follow the authentication flow to obtain a Bearer token.
Set Up Headers: Include the following headers in your requests:
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
These endpoints can be combined with other categories for more advanced integrations, such as:
Company Management: After creating a company using the Create Company endpoint in the Company Management category, use the Create/Update User or Create/Update Admin endpoints to add users and admins to the company.
Locations & Programs: Use the List Company Locations and List Company Programs endpoints in the Locations & Programs category to retrieve location and program IDs, then assign users or admins to them using the Create/Update User or Create/Update Admin endpoints.
Activity Results: After assigning users to a company, location, or program, use the List Activities endpoint in the Activity Results category to retrieve activity data for those users.
Additional Resources
Postman Collection: Explore the full R1 Discover API Postman collection for pre-built requests and examples: R1 Discover API Postman Collection.
Support: For further assistance, contact the R1 Discover API support team at [email protected].
Changelog: Stay updated with the latest API changes by reviewing the API Changelog.
Last updated