AlayaCare Intake API Guide
Documentation around AlayaCare’s service for sending referrals and its respective data elements.
Contents
- Overview
- Validation
- Data Flow
- Message Structure
- Sample Referral Message
- Referrals on the Web Interface
Overview
AlayaCare Intake leverages a flexible JSON message structure to capture client, contact, and service details and display them in the AlayaCare web interface for a coordinator to evaluate and process.
AlayaCare Referrals can create a client profile, client contact profiles, and a line of service at the click of a button. Referrals are the only supported method for creating services in AlayaCare via external integrations, and the ability to gather data from multiple entities into a single message offers a powerful tool for integration projects. Processing a referral from the web interface creates separate entities in AlayaCare based on the referral data. The sample message below includes a client, service, and client contacts.
Referrals are sent through an inbound message queue called the intake queue. Once they are processed, AlayaCare event queues using AWS SNS/SQS will stream an event that a client, service, and/or contact entities were created.
Validation
AlayaCare has a built-in validator for referral messages to ensure no mandatory fields are missing. If a referral message is not valid, it will not appear in the web interface to end users. As part of the project, AlayaCare will work with your team to establish the format of the validator custom to your Intake implementation.
Data Flow
Message Structure
Message Architecture
Summary
The “Summary” section of a referral is a configurable set of keys from the main body of the referral. The purpose of this section is so the web interface includes a “Summary” section useful to coordinators for “at a glance” reviews of referrals.
Client
Demographics
Within the client object, there is a demographics section that is a completely customizable dictionary of key,value pairs configured on the Form Context page in the AlayaCare web app. The sample message below shows common values for this section such as first_name, last_name, phone, etc.
Service
Funders
The funders object is optional, and it is important to note that not every referral integration requires funding details. The funding methodology of a service may be sent in the referral message. The funders can be referenced either by external ID or by their AlayaCare ID.
Profile
Within the service object, there is a profile section that is a completely customizable dictionary of key,value pairs configured on the Form Context page in the AlayaCare web app. The sample message below shows common values for this section such as service_name, client_type, pharmacy_name, etc.
These labels and values will appear in the “Details” section of a service profile on the web interface.
Provider Details
The provider_details object is a dictionary of additional data attributes related to the service, however, unlike the service profile, these keys do not need to be configured. Any key,value pair sent in this section will display as labels and values in the “Latest Referral Info” section of a service profile on the web interface.
The sample message below shows some common keys in this dictionary.
Contacts
Client contacts have a customizable demographics profile with the same functionality as the demographics section for a client: the keys for this object are configured in the Form Context module of the AlayaCare web app. Client contacts can be categorized into three possible types: personal, medical, or source.
Sample Referral Message
Message headers
status is hardcoded to a value of Posted.
transmission_date is required; its value is stamped from the sending system external to AlayaCare.
payload is the required name for the referral message body.
JSON Example
{
"status": "Posted",
"transmission_date": "2019-03-01T13:27:45-05:00",
"payload": {
"Type": "New",
"tracking_id": "90bc725c-c099-4d7b-8b9c-1180cb18e9c8",
"client": {
"external_id": "external_client_id",
"demographics": {
"zip": "H2W2R2",
"city": "Montreal",
"email": "spider@gotham.com",
"state": "QC",
"gender": "M",
"address": "4200 Blvd St-Laurent",
"country": "Canada",
"language": "en",
"last_name": "Parker",
"first_name": "Peter",
"phone_main": "514-555-6666",
"client_type": "Commercial",
"phone_other": "514-777-8888",
"address_suite": "800",
"client_status": "Pending Enrolment",
"phone_1_details": "Details for Phone 1",
"phone_2_details": "Details for Phone 2",
"primary_address_type": "Home"
},
"service": {
"external_id": "System of Record ID",
"service_instructions": "These are the service instructions",
"name": "Infusion Service (Weekly)",
"funders": [
{
"percentage": 100,
"external_id": "5"
}
],
"profile": {
"zip": "H2W2R2",
"city": "Montreal",
"state": "QC",
"address": "4200 Blvd St-Laurent",
"country": "CA",
"billed_to": "peterparker@thecave.com",
"client_type": "Commercial",
"address_suite": "800",
"client_status": "Pending Enrolment",
"pharmacy_name": "Corner Drug Store",
"treatment_name": "Homecare",
"delivery_method": "Home",
"appointment_date": "2018-05-30",
"service_instructions": "These are the service instructions",
"treatment_location": "Main Street Clinic",
"primary_address_type": "Home"
},
"provider_details": {
"treatment_orders": "These are the point of care instructions",
"unit_of_service_1": "Visits",
"provider_instructions": "Instructions for intake coordinator"
}
},
"client_contacts": [
{
"external_id": "",
"demographics": {
"remarks": "Please call only after 6pm and no later than 10pm",
"last_name": "",
"first_name": "HomePhone",
"phone_main": "2178222079",
"contact_type": "Personal"
}
},
{
"external_id": "",
"demographics": {
"fax": "1-800-HOME-CARE",
"email": "prescribing_physician@hospital.com",
"last_name": "Calvin",
"first_name": "Phillip",
"phone_main": "7095799400",
"contact_type": "Medical",
"relationship": "Physician",
"md_preferred_method_of_contact": "Fax",
"md_appointment_cancellation_notification": false
}
}
]
}
}
}
Referrals on the web interface
Details of a Single Referral
Referral Message Inbox
Form Context Module
