Rethink BH API Specs
SIGNED OFF SE 2/11/20
1. Overview
This specification is intended to document the requirements for using the Rethink Behavior Health for receiving information from 3rd party practice management and EHR software. This interface includes clients, staff/providers, visits, and the ability to send data related to client, staff, and visit modifications.
2. Intended Audience
The intended audience of this document is:
· Project Management and Technical teams at Rethink.
· Project Management and Technical teams at a designated Providers/Vendors who will be implementing this interface.
3. Transmission Frequency
For optimal system performance, it is recommended that visits should be sent in near real time. It is expected that information is sent as it is added/changed/deleted in the customers’ practice management or EHR software. Note that completion response will be sent back to the EHR software in a separate call back API
4. Transmission Limits
· An initial load of clients and staff will be done before the API is turned on
· A transaction record will have only one record at a time
Data Type Format Details
The user will send information in JSON format. The format of the information sent must match exactly the format defined below and must be sent via web service using JSON. Ultimately, we support only three data types during transmission: String, number and Boolean. The specification uses more additional data types to ensure that data is received in the expected formats and appropriate record level editing can be incorporated. Except where numeric, the assumed JSON format should be String. The data type provided in the specification is based on the following field definitions.
Note that the format is case sensitive. All field names must be provided in EXACTLY the casing used in the definitions below. Rethink recommends using RESTful services with JSON formatting.
Data Type | Description | Example |
DateTime
| The date and time is represented as a string with the following format: YYYY-MMDDTHH:MM:SS All times will be provided in UTC. | 2016-12-20T16:10:28Z
|
Date (only Date) | The data is represented as a string with the following format: YYYY-MM-DD Date only will be sent in ETC format. | 2016-12-20
|
Timezone | All time for tracking visits will be in UTC. Timezone values are based on the Internet Assigned Numbers Authority (IANA) Time Zone Database, which contains data that represents the history of local time for locations around the globe. | A complete list of time zones can be found at: https://www.iana.org/timezones See Appendix for list of EVV supported Timezones
|
String | A string is a row of zero or more characters which can include letters, numbers, or other types of characters as a unit, not an array of single characters. (e.g. plain text).
|
|
Integer | An integer is a numeric value without a decimal. Integers are whole numbers and can be positive or negative. | 52110 (positive) -87721 (negative) |
Decimal | A floating point number is referred to as a decimal. Can be positive or negative. | 8221.231 (positive) -71.214 (negative) |
Boolean | A logic predicate indicator that can be either true or false. | True False |
New Record Process
In case the customer system is the master of records for staff, clients, and appointments, the system will push new records to Rethink in almost real-time fashion. New staff, clients or visits/appointments will be synced to Rethink via API calls.
The customer system will not send record ID for the new records being created so that Rethink system will understand it is a new record being added.
Any record created in Rethink using the API, Rethink will return an acknowledgement and record ID so that the source system will map Rethink record ID into the corresponding entity in the source system.
Creating a visit/appointment in Rethink will require that the source system sends client ID, and staff ID as part of the API call
Update Record Process
The same API end points will be used for both create and update entities in Rethink. For update scenarios, the client system will be sending the Rethink record ID with the API call so that Rethink will know it is a record being updated.
Failed/Rejected Record Process
Failure to create records in Rethink due to any validation error or any other technical reason will result into an Error code and message being passed back to the calling system as a response to the API call. A list of known error codes and messages will be detailed later.
Error Handling
Below is a list of business validations that we need every API to check for.
Upon successful insert operation, the API will return the same input object with Rethink ID’s added to each entity (e.g clientid, clientfunderID, clientAuthID, etc.)
If any of the following errors occurred in any of the objects, Rethink will return the object with null ID and a String description of the error based on the below ErrorMessage in the field “ErrorMessage” of that object
# | Scenario | Description | Error Message |
1 | A required field is not sent during Insert |
| [Field Name] is required. Rethink API will return this error message with the actual field name. |
2 | Max length of a field |
| [Field Name] length exceeded |
3 | Invalid ID for a lookup | If the API client sends an incorrect ID for a Rethink lookup (e.g. Client Status ID), Rethink API will fail to find this status | Invalid [Field] ID. The error message will indicate the actual field whose ID is incorrect. Please reference the Rethink lookup https://rethinkautism.atlassian.net/wiki/spaces/RBS/pages/3663626421 for ID’s. |