Locations & Programs
An overview of the Locations & Programs collection of endpoints.
Overview of Locations & Programs
The Locations & Programs category in the R1 Discover API provides a set of endpoints designed to manage the locations and programs associated with companies. These endpoints are critical for organizing the physical or virtual facilities (locations) where a company operates and the programs offered at those locations, such as treatment or educational programs. Proper management of locations and programs ensures that companies can effectively structure their operations, assign users to specific locations or programs, permission their teams, and deliver targeted content or services.
This category is particularly useful for administrators or developers who need to programmatically manage a company’s operational structure, ensuring that locations and programs are accurately represented, permissioned, and linked within the R1 Discover platform.
Endpoints in This Category
The "Locations & Programs" collection includes the following endpoints:
List Company Locations Retrieve a paginated list of locations associated with a specific company or across all companies, including details such as location name and status.
Create/Update Location (upsert) Create a new location for a company or update an existing location’s details, such as its address, contact information, or status.
List Company Programs Fetch a list of programs associated with a specific company or across all companies, including program names, parent programs, and status.
Create/Update Program (upsert) Create a new program for a company or update an existing program’s details, such as its name, parent program, or status.
List Parent Programs Retrieve a list of parent programs (e.g., ASAM levels) that can be associated with company-specific programs, useful for categorizing programs hierarchically.
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 section.
Use Cases
The Locations & Programs endpoints are typically used in the following scenarios:
Operational Setup: Use the Create/Update Location endpoint to set up or modify a company’s locations, ensuring accurate representation of physical or virtual facilities.
Program Management: Leverage the Create/Update Program and List Company Programs endpoints to define and manage programs offered by a company, such as detox or outpatient services.
Hierarchical Organization: Use the List Parent Programs endpoint to retrieve parent program categories (e.g., ASAM levels) and associate them with company-specific programs using the Create/Update Program endpoint.
User Assignment: After setting up locations and programs, assign users to them using endpoints from the User Management category, ensuring users are linked to the correct operational context.
Data Synchronization: Integrate these endpoints into your system to keep location and program data in sync with the R1 Discover platform, ensuring consistency across applications.
Best Practices
Authentication: Always include a valid Bearer token in the Authorization header to avoid 401 Unauthenticated errors.
Pagination: Endpoints like List Company Locations, List Company Programs, and List Parent Programs support pagination parameters (page and limit). Use these to manage large datasets efficiently and avoid performance issues.
Sorting Options: Utilize sorting parameters (e.g., sortby, locationOrder, programOrder) to organize results in a way that best fits your application’s needs (e.g., oldest, newest, alphabetical).
Error Handling: Be prepared to handle common errors such as 401 Unauthenticated, 403 Unauthorized, and validation errors (e.g., missing required fields in Create/Update Location). Refer to the individual endpoint documentation for detailed error responses.
Data Validation: When using Create/Update Location or Create/Update Program, ensure that required fields (e.g., location_name, name, status) are provided and conform to expected formats to avoid validation errors.
Hierarchical Consistency: When creating or updating programs, use the List Parent Programs endpoint to ensure that the parent_id provided in Create/Update Program corresponds to a valid parent program.
Integration Points
To effectively use the Locations & Programs 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 Location and Create/Update Program endpoints to set up its locations and programs.
User Management: Once locations and programs are defined, use the Create/Update User endpoint in the User Management category to assign users to specific locations or programs, ensuring proper operational alignment.
Global Endpoints: Use the List Countries endpoint in the Global Endpoints category to populate country fields when creating or updating a location via the Create/Update Location endpoint.
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