The information contained in this document is confidential, privileged, and only for the use of internal Birdeye users. This document may not be used, published or redistributed.
This integration is supported for both SMB & Enterprise businesses.
Integrating Birdeye with AthenaHealth
User Manual - SUPPORT ARTICLE
AthenaHealth is an Electronic Health Records (EHR) system used by physicians, hospitals, and medical communities. Users are able to manage electronic health records, medical billing, patient engagement, care coordination, etc. with AthenaHealth. Integrating AthenaHealth with Birdeye will automate the process of sending out review requests to patients on a daily basis.
Table of Contents
Information required from the Business
Trigger details
Login
Manage Triggers
Manage Properties
Manage Locations
Integration Requirements
Triggers supported
Birdeye allow you to fetch data from your CRM using a predefined trigger. Here is the supported trigger for AthenaHealth:
Trigger Display Name | Trigger Name/Value | Trigger Description |
Athena Health Completed Appointment Trigger | Appointment | This trigger is used to fetch customer data based on the completed appointments. |
Appointment Trigger Service | Appointment Trigger | This trigger is used to update appointments created via the Birdeye widget (Writeback in PMS). It's required for reminders. |
Athenahealth Appointment Upsert Trigger Service | Athenahealth Appointment Upsert Trigger | This trigger is used to upsert appointments created/Updated via PMS. It's required for reminders. |
Details required from the Birdeye client
NOTE: As a primary step, the customer should authorize Birdeye to fetch data from AthenaHealth by filling out an Authorization and Consent form. The same should also be confirmed by the customer. There are 2 ways any business can be set up in Athena. If the client has set up each of his departments/locations as a business in Birdeye then go with setup 1 else if each physician/provider is mapped to a business in Birdeye then go with setup 2. Birdeye can fetch appointments based on either department id (setup 1) or the NPI number of the physician/provider (setup 2).
Setup 1 - Each business in Birdeye is a location/department in Athena
Trigger details
AthenaHealth practice ID
AthenaHealth department ID
Setup 2 - Each business in Birdeye is a provider/physician in Athena
Trigger details
AthenaHealth practice ID
Provider NPI number
NOTE:
Setup 1 -
For Single Location: There will be one practice ID and department ID(s) for that location.
For Multi-Location: There can be one or many practice ID(s) with multiple department IDs under them for each location.
Setup 2 -
For Single-location: There will be one practice id and one NPI number for that business.
For Multi-location: There can be one or many practice ID(s) with multiple Provider NPIs (each corresponds to a business number in Birdeye) under them.
In case, the customer does not have the department ID, it can be fetched using the practice ID (provided he knows the department name) as described in these steps.
Details required from the Birdeye dashboard
Enterprise ID for a multi-location account and Business ID for all locations.
Business ID in the case of an SMB Business.
Information from Birdeye Dashboard
For single location SMB account - Business ID
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Integrations’ and select ‘API.’
You will find the ‘Business ID’ and ‘API key’ shown in the image.
For multi-location account - Enterprise ID and Business IDs of all locations
Enterprise ID
Business IDs of all locations
Login to your Birdeye account, go to Left Navigation Rail and click on ‘Settings’. Once the new page appears, click on ‘Profile’ and select ‘Business Profiles.’
To view Location ID, hover over the ‘Status’ of location.
Integration Process
Before you can integrate Athena Health with Birdeye, you will need to set up the following configurations on the integration support dashboard:
To set up native integration, we have an integration support dashboard, where we need to set up the integration and then follow these steps to complete the configuration.
Login
After successful login in the integration dashboard, you have to click on ‘BE integration’ and then click on ‘Add Integration.’
Search for the CRM in the search bar and select it. Click on ‘Next’.
Manage Triggers
The trigger is automatically selected as only one trigger is supported.
Note: To fetch information for all the triggers available using curl commands, use this command. To replace triggers use this curl command.
Manage Properties
Here; you can manage group-level properties, which will be applied to all locations under a CRM.
Customer fetch delay: It is used if businesses want to send review requests with a delay (number of days).
Show All departments: Set the value to ‘true’, if the customer wants us to fetch the appointment of all the departments (for any practice ID) which are not visible in AthenaHealth, else set it to ‘false.’
Note: This step will create a group for our integration. Alternatively, you can do it via curl commands.
For SMB accounts you can access the curl command.
For Enterprise accounts, you can access the curl command.
Manage Locations
For Single Location/Multi-Location Accounts, select the location from the drop-down menu and click on ‘Add.’
(In the case of Single Location accounts, it will give you only one option).
A drawer will appear on the right-hand side.
The Status, Frequency, and Next Runtime will be set by default. You can make the changes if required.
Status: It shows the status of Integration (Active or Inactive).
Frequency: The number of times integration will sync with CRM (Days or Hours).
Next RunTime: The next scheduled time when the integrations will run.
Future Duration (in months): You can leave it blank if there is no specific requirement. If left blank, we shall fetch appointments for the coming 12 months. If you want to change this duration, enter that duration(in months). This property is used for reminders.
For instance, if you want future appointments of the next 5 months only to be fetched, you should enter 5 here.Past Duration (months):For reminders, please enter the number of months for which past appointments have to be fetched.
NOTE: If not entered, the past 6 months' appointments will be fetched.Cancellation Reason ID: It will only be used for reminders if the business uses reminders via Birdeye. Enter the cancellation reason ID, which will be used to cancel appointments via Birdeye. (Here, Practice ID will be that of the business and use access token for that business.)
To fetch cancellation Reason ID, please use the following curl:
curl --location --request GET 'https://api.platform.athenahealth.com/v1/practiceId/appointmentcancelreasons' \--header 'Authorization: :censored:6:068cbbe057: accessToken'
Appointment status: Enter the appointment status values as requested by the customer. The review requests will be sent to those appointment statuses only. To pull the appointment of the closed status, use value ‘3,4’.
Provider NPI number: Enter the NPI number of the physician only if every physician is a location in Birdeye. The customer will provide the NPI number.
Practice ID: Enter the practice id provided by the customer.
Department ID: Enter the department id only if every department is a location in Birdeye. The customer will provide the department ID. If the customer does not have the department ID, it can be fetched using the practice ID (provided he knows the department name) as described in these steps. For Appointment Reminders, adding department IDs here will ensure that for this Birdeye location, we shall only consider appointments of those departments.
Customer fetch delay: It is used if businesses want to send review requests with a delay (number of days).
Override Group Properties: With this, you can override the properties added at the group level, specific to each location.
Note:
For SMB: You can use ‘manage the locations’ using this curl command.
For Enterprise: You can use ‘manage the locations’ using this curl command.
Curl Commands
Before you can integrate AthenaHealth with Birdeye, you will need to set up the following configurations:
A business integration group is a configuration that supports the business hierarchy of individual businesses on the Birdeye platform. The properties that are common for all business integrations are entered at the group level. Setting up a business integration group allows you to associate multiple business locations with the Enterprise account. Below is the list of curl commands that you will need to run to set this up.
Create Integration Group (Curl Command)
Copy this Curl Command
curl-X PUT https://common-services.Birdeye.com/integration/add/businessintegrationgroup -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -d '{ "parentBusinessNumber":151811039105799, "isOauthEnabled":false, "integrationGroupProperties":[ { "propertyKey" : "showalldepartments", "propertyValue": "false" } ], "integrationSourceId":27, "integrationGroupTriggers":[{"triggerId":42,"triggerTypeId":1}]}'151811039105799 - Business ID - This is Enterprise ID for multi-location account and Business ID for a single location SMB account
false - “showalldepartments” - You can set the “showalldepartments” value to true, only if you want to fetch the departments that are hidden in the portal. If not, then keep the value false.
42 - Integration Trigger ID - Can be one or more triggers. Ask the client what trigger they would like to integrate with, then run the curl command to fetch all possible triggers for AthenaHealth. Identify the trigger ID(s) and insert (use commas) in the case of multiple trigger IDs.
Fetch information for all the triggers available for AthenaHealth (Curl Command).
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/trigger/integrationtriggers/sourceid/27 -H 'cache-control: no-cache' -H 'content-type: application/json'
Sample response: A sample response like this would appear after you run the curl command. The response will have the trigger name, description and ID. This trigger Id will be utilized while creating the integration group. Integration can have one or more triggers. To use more than one trigger, enter comma-separated values while creating the integration group.
[{"id": 42,"integrationSourceId": 27,"triggerService": "athenaHealthIntegrationTriggerService","displayName": "Athena Health Completed Appointment Trigger","description": "This trigger is used to fetch customer data based on the completed appointments.","active": true,"integrationSourceName": "AthenaHealth","integrationTriggerType":[{"id":1,"name":"JOB"}]}]42 - Trigger ID
Find business integration group details (Curl Command)
Copy this Curl Command
curl -X GET https://common-services.Birdeye.com/integration/businessintegrationgroup/151811039105799 -H 'Cache-Control: no-cache
151811039105799 - Business ID: Enter the Business ID here to get the integration group details for a business.
Sample Response:
[{"groupId": 253,"integrationSourceType": {"id": 27,"integrationSource": "AthenaHealth","sourceCategory": "Healthcare","oauthEnabled": false},"integrationGroupTriggers": [{"triggerId": 42,"triggerTypeId": 1}]}]253 - Group ID: A group ID will be returned in the sample response with the details of the existing triggers for a business.
Update Triggers Information (use only if a business wants to change) (Curl Command)
Copy this Curl Command
curl -X POST 'https://common-services.Birdeye.com/integration/update/businessintegrationgroup?replaceTriggers=true' -H 'cache-control: no-cache' -H 'content-type: application/json' -d '{ "groupId": 253,"integrationGroupTriggers":[{"triggerId":45,"triggerTypeId":1}]}'replaceTriggers=true - To replace existing trigger(s), enter the value for replaceTriggers as To add a new trigger(s) to the existing list, the value for replaceTriggers should be false
253 - The Group ID that was returned in the previous step will be entered here.
45 - Enter the Trigger ID(s) that need to be added or updated to the integration.
Integration Mapping For Setup 1 (By Department ID):
Once the Integration Group is created, the next step is to create the Integration Mapping.
Copy this Curl Command
curl -X PUT https://common-services.Birdeye.com/integration/add/businessintegrationmapping -H 'Accept: application/json' -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -d '{ "businessNumber": 152174018901056, "integrationGroupId" : 253, "active": true, "integrationProperties":[ { "propertyKey" :"appointmentstatus", "propertyValue" :"3,4" }, { "propertyKey" :"practiceid", "propertyValue" :"1959568" }, { "propertyKey" :"departmentid", "propertyValue" :"1" } ] } '3,4 - Appointment Status: The value 3,4 is for closed appointments. If the user wants to fetch appointments of any other status, then the appointment status will be shared by the AthenaHealth client during the initial setup.
1959568 - Practice ID: Enter the Practice ID which was shared by the client during the initial setup.
1- Department ID: Enter the Department ID, which was shared by the client during the initial setup.
Integration Mapping For Setup 2 (By Provider NPI Number)
Once the Integration Group is created, the next step is to create the Integration Mapping.
Copy this Curl Command
curl -X PUT https://common-services.Birdeye.com/integration/add/businessintegrationmapping -H 'Accept: application/json' -H 'Cache-Control: no-cache' -H 'Content-Type: application/json' -d '{ "businessNumber": 153116587943454, "integrationGroupId" : 315, "active": true, "frequency" : "1 DAYS", "integrationProperties":[ { "propertyKey" :"appointmentstatus", "propertyValue" :"3,4" }, { "propertyKey" :"practiceid", "propertyValue" :"1959568" }, { "propertyKey" :"athenaProviderNpi", "propertyValue" :"1134161995" } ] }'3,4 - Appointment Status: The value 3,4 is for closed appointments. If the user wants to fetch appointments of any other status, then the appointment status will be shared by the AthenaHealth client during the initial setup.
1959568 - Practice ID: Enter the Practice ID which was shared by the client during the initial setup.
1134161995 - Provider NPI Number: Enter the Provider’s NPI number, which was shared by the client during the initial setup.
Available Appointment Status List:
The ‘Appointment status’ is the current status of any booked appointment. It is used to filter the appointments by their status. Here are the different appointment statuses:
Appointment Status | Details |
appointmentstatus=2 | Checked In |
appointmentstatus=3 | Checked Out |
appointmentstatus=4 | Charges Entered |
appointmentstatus=f | Filled appointments |
appointmentstatus=x | Cancelled appointments |
How to find Department ID
Step-1: Run this curl to get the accessToken.
curl --location --request POST 'https://api.platform.athenahealth.com/oauth2/v1/token' \--header 'Content-Type: application/x-www-form-urlencoded' \--header 'Authorization: Basic MG9hNzJsMzQyY1RzQU5tRFUyOTc6ZldIY096aE9QclYwbVd2clMtNmlyaE5XVS1yN1dmX011RjA5cWFhUg==' \--data-urlencode 'grant_type=client_credentials' \--data-urlencode 'scope=athena/service/Athenanet.MDP.*'
You will get the below result which contains the accessToken, copy the accessToken for finding the department ID.
Step-2: Pick the accessToken from the previous response and paste it into this request and fill in the ‘practiceid’ of the business.
curl --location --request GET 'https://api.platform.athenahealth.com/v1/321/departments' \--header 'Authorization: :censored:6:068cbbe057: poHrznht1dtGu5dKjfQQeoxvbQFY' \--header 'Content-Type: application/json' \--header 'Accept: application/json'
You would get the response as below that you may see in postman or copy and view on a Json viewer website.
Step-3: The “Response Body” section contains the information of all the location names and their respective department ids. The “totalcount” field lists the number of locations/department IDs in AthenaHealth.
NOTE: There will be multiple repeated sections of the response object, each containing “departmentid” and “name”.
How to validate Practice ID
In case you need to validate a practice ID provided by the client and is not working, you need to run the below curl command and put the practice ID value as ‘1’, and the response will contain a list of all the practices that Birdeye has access to.
curl --location --request GET 'https://api.platform.athenahealth.com/v1/1/practiceinfo' \--header 'Authorization: :censored:6:068cbbe057: poHrznht1dtGu5dKjfQQeoxvbQFY' \--header 'Content-Type: application/json' \--header 'Accept: application/json'
You would get the response as below that you may see here or copy and view on a JSON viewer website.
Re-Authorise Business
Sometimes, it happens the credentials entered were wrong during setup or are expired, so we receive 401 Unauthorized Error while running the Integration. As a result, Integration will be marked unauthorized. It will not run until the credentials are corrected and the business is authorized again, which involves the steps given in the below document.
Campaigns Tags
Campaign tags are used to set up campaigns within the Birdeye dashboard. These tags are either provided by the client or can be fetched from Kibana for already checked-in contacts.
AthenaHealth Campaign tags are:
pms_appointment_procedure_code , NPI ID
Raise Support Case
Use the below credentials to raise Athena Health support cases.
Support Portal Login Url: https://athenahealth.force.com/Marketplace/s/login/
Username: athenahealth@Birdeye.com
Password: Birdeye#123
Restriction Reason
Restriction reason is used to identify the contacts which have been opted-out(restricted) from sending a review request. This reason can be fetched from Kibana for contacts that are checked in already.
Possible restriction reasons for AthenaHealth are
‘Appointment status’ is not on the allowed list
Integration is beta
Description
The appointment status is different from those present in the allowed list of status.
The integration setup is currently set to beta.