AlayaCare API: Automate Referral Intake and Scheduling

We built and shipped an AlayaCare integration that: accepts inbound referrals through the official Intake channel, provisions client and service records, triggers caregiver scheduling on assignment or shift changes, and sends HIPAA-safe family status updates without exposing health details. It fits home care operators that want speed-to-care and auditability. This guide explains exactly how we wired it, the caveats we hit, and how you can replicate it safely.

AlayaCare API integration is the practice of connecting AlayaCare's External REST API, Intake messaging, and Marketplace event streams to your own systems so referrals, schedules, and notifications flow automatically.

The problem it solves

Manual intake and scheduling in home care looks like this: a coordinator reads a referral email or portal entry, re-keys demographics, creates a line of service, calls or texts caregivers to fill the visit, and finally messages the family. It is slow, error-prone, and hard to audit. A missed handoff means delayed care. A copied health detail in the wrong channel becomes a compliance risk.

According to IBM's 2023 Cost of a Data Breach Report, healthcare breaches averaged 10.93 million dollars per incident, the highest of any sector (source: https://www.ibm.com/reports/data-breach). Reducing re-keying and keeping PHI out of messaging channels is not just good hygiene. It is material risk reduction.

How the automation works

At a high level: referrals enter through AlayaCare's Intake channel to create the client and a line of service. We subscribe to Marketplace events or poll the Scheduler area to detect assignment and timing changes. A rules layer translates those events into caregiver routing tasks and family-safe notifications. For bulk or accounting-grade outputs we consume CSV flat files from S3 when available.

• External REST API: Tenant-scoped base path with HTTP Basic auth using an AlayaCare public and private key. We use the Clients, Employees, and Scheduler areas for reads and controlled writes where supported.
• Intake referrals: The only supported path to create services programmatically. We publish Intake messages to the inbound queue so AlayaCare creates the client, contact, and line of service.
• Marketplace events: Token-based auth to regional endpoints. We consume async events via AWS SNS where configured to react to schedule changes without polling.
• Flat-file exports: CSV files over S3 with AES256 at rest, plus SNS signals when files land. Useful for reconciliations and downstream reporting.
• HIPAA-safe notifier: A small service that builds family updates from non-health fields only, aligning with AlayaCare's guidance that outbound event queues exclude health data.

Step-by-step: how to build it

1) Authenticate to the External API with HTTP Basic

Answer first: AlayaCare's External API uses your tenant domain and HTTP Basic with a public and private key. We keep keys in a secrets manager and compose Basic auth per request.

// Node.js example: External API auth and a guarded GET
import fetch from "node-fetch";
 
const TENANT = process.env.ALAYACARE_TENANT; // e.g., example.alayacare.ca
const PUB = process.env.ALAYACARE_PUBLIC_KEY;
const PRIV = process.env.ALAYACARE_PRIVATE_KEY;
 
function basicAuth() {
  const token = Buffer.from(`${PUB}:${PRIV}`).toString('base64');
  return `Basic ${token}`;
}
 
export async function acGet(areaPath) {
  const url = `https://${TENANT}/ext/api/v2/${areaPath}`; // areaPath: Clients|Employees|Scheduler/...
  const res = await fetch(url, { headers: { Authorization: basicAuth() }});
  if (!res.ok) throw new Error(`AlayaCare ${res.status} ${await res.text()}`);
  return res.json();
}

What tripped us up was environment drift: staging and production tenants each have their own key pairs. We pin keys per environment and assert the expected hostname before every call.

2) Send Intake referral messages to create client and service

Answer first: services cannot be created via standard REST. Referrals are the supported method to create services, so we publish Intake messages to the inbound queue.

// Example Intake message payload construction (shape depends on your setup)
const intakeMsg = {
  referralSource: "Hospital A",
  client: {
    firstName: "Alex",
    lastName: "Smith",
    primaryPhone: "+1-555-0100",
    address: { line1: "123 King St", city: "Toronto", postalCode: "M5H 2N2" }
  },
  contact: { name: "Jordan Smith", relation: "Spouse", phone: "+1-555-0101" },
  lineOfService: { program: "Personal Support", priority: "High" },
  notes: "Referral via discharge planner. Preferred mornings."
};
 
// Publish to your configured Intake queue (AWS SDK example)
import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
const sqs = new SQSClient({ region: process.env.AWS_REGION });
await sqs.send(new SendMessageCommand({
  QueueUrl: process.env.ALAYACARE_INTAKE_QUEUE_URL,
  MessageBody: JSON.stringify(intakeMsg)
}));

We validate against AlayaCare's intake guide and maintain a contract test so a schema change fails fast in CI instead of in production.

3) Consume Marketplace events or poll Scheduler for triggers

Answer first: for near real time, consume Marketplace events via SNS when enabled. Where events are not provisioned, poll the Scheduler area on a cadence.

// SNS subscription confirm + event handler (Express)
app.post("/alayacare/events", async (req, res) => {
  const msgType = req.get("x-amz-sns-message-type");
  const body = req.body;
  if (msgType === "SubscriptionConfirmation") {
    await fetch(body.SubscribeURL); // confirm subscription
    return res.status(200).end();
  }
  if (msgType === "Notification") {
    const event = JSON.parse(body.Message);
    // e.g., schedule-assignment-changed (exact topics are provisioned per account)
    await handleScheduleEvent(event);
    return res.status(200).end();
  }
  res.status(400).end();
});
 
// Fallback: poll Scheduler area for changes since a watermark
const since = new Date(Date.now() - 5 * 60 * 1000).toISOString();
const delta = await acGet(`Scheduler/changes?since=${encodeURIComponent(since)}`);

Note: Marketplace subscriptions are not self-serve. We coordinated enablement by email per AlayaCare's guidance.

4) Route assignments and guard against double-booking

Answer first: when an event indicates an assignment need, we select eligible caregivers and idempotently write back or notify, with a dedupe key on visit and caregiver.

# Python: select caregivers and prevent duplicate work
from hashlib import sha1
 
seen = set()
 
def key(visit_id, caregiver_id):
    return sha1(f"{visit_id}:{caregiver_id}".encode()).hexdigest()
 
for visit in pending_visits:
    eligible = match_caregivers(visit, caregivers)
    for cg in eligible:
        k = key(visit.id, cg.id)
        if k in seen: continue
        seen.add(k)
        enqueue_assignment_attempt(visit, cg)

We treat AlayaCare as the source of truth for schedule state and keep our routing stateless beyond a short-lived dedupe cache, which kept retries safe.

5) Send HIPAA-safe family status updates

Answer first: build messages only from non-health data because outbound event queues exclude client health details. Families get timing and assignment status, never diagnoses or clinical notes.

function toFamilyUpdate(event) {
  // Whitelist non-health fields only
  const safe = {
    clientName: event.client?.displayName,
    visitStart: event.visit?.startTime,
    visitEnd: event.visit?.endTime,
    caregiverFirstName: event.caregiver?.firstName,
    status: event.status // e.g., Assigned, Confirmed, En Route
  };
  return `${safe.clientName}: ${safe.status}. ` +
         `Window ${new Date(safe.visitStart).toLocaleTimeString()}, ${new Date(safe.visitEnd).toLocaleTimeString()}. ` +
         (safe.caregiverFirstName ? `Caregiver: ${safe.caregiverFirstName}.` : "");
}

We log every outbound message with hashed identifiers and redact at the edge. Storage at rest uses AES-GCM with rotation, and access is limited to the automation service.

6) Process flat-file CSV exports from S3 for reconciliations

Answer first: for accounting and EVV reconciliations, consume CSV exports over S3 with event notifications to kick off processing.

# AWS Lambda: S3 ObjectCreated handler for CSV exports
import csv, boto3
 
def handler(event, context):
    s3 = boto3.client('s3')
    bucket = event['Records'][0]['s3']['bucket']['name']
    key = event['Records'][0]['s3']['object']['key']
    obj = s3.get_object(Bucket=bucket, Key=key)
    rows = csv.DictReader(obj['Body'].read().decode('utf-8').splitlines())
    for row in rows:
        upsert_reconciliation(row)  # idempotent write

We treat file arrivals as eventual-consistency signals. A simple idempotent upsert prevents duplicate entries if SNS retries.

Where it gets complicated

• You cannot create services via standard REST: Referrals are the supported method to create services. We moved all programmatic provisioning into the Intake channel and validated payloads against the intake guide.
• Marketplace subscriptions are not self-serve: You must coordinate enablement by email. We built a fallback poller against Scheduler so scheduling triggers still run if events are delayed.
• Outbound events exclude health data: That is a feature, not a bug. We designed our family-update layer to rely only on non-health fields and kept PHI out of transport.
• No public Zapier/Make app we could rely on: We did not find an official connector. AlayaCare markets its own Connector product. We integrated directly with the External API, Intake, and AWS SQS/SNS to avoid vendor lock-in.
• Environment sprawl: Regional Marketplace base URLs and tenant domains differ. We pinned environment variables per tenant and asserted hostnames to avoid cross-posting.

What this actually changes

For a home care operator, this removed re-keying from referral to service creation, cut the time to first caregiver contact, and standardized family messaging into a safe template. The change is structural: the Intake channel becomes the single source of truth, events drive actions, and messaging flows from non-health data by design. Healthcare leads the world in breach costs at an average of 10.93 million dollars per incident in 2023 (IBM: https://www.ibm.com/reports/data-breach). Keeping PHI out of status updates and reducing manual copy-paste meaningfully lowers exposure while improving speed-to-care.

Frequently asked questions

Does AlayaCare have an official API?

Yes. The External REST API lives under your tenant domain and uses HTTP Basic with a public and private key. Areas include Clients, Employees, Scheduler, Tasks, Files, and Clinical. The Marketplace also exposes regional endpoints with token-based auth and SNS-style events.

How do you create services through the API?

You do not via standard REST. Referrals are the supported method for creating services. We publish Intake messages to the inbound queue so AlayaCare creates the client, contact, and line of service according to the intake guide.

Can I get real-time webhooks from AlayaCare?

The Marketplace supports async eventing via SNS. Subscriptions are not self-serve, so you coordinate enablement by email. Where events are not provisioned, polling the Scheduler area on a short cadence is a practical fallback.

Is there a Zapier or Make.com integration for AlayaCare?

We did not find a public Zapier or Make app to rely on. AlayaCare offers its own Connector no-code product. We integrate directly with the External API, Intake, and SQS/SNS so you are not gated by third-party app coverage.

How do you keep family updates HIPAA-safe?

We only use non-health data from outbound events: timing, assignment state, and caregiver first name where appropriate. No diagnoses or clinical notes. Messages are templated, logged with hashed identifiers, encrypted at rest, and access-controlled.

How long does this take to implement?

We start with Intake and one scheduling trigger so you see value quickly, then expand to more programs and notifications. Timeline depends on event access and mapping scope. The pattern above lets you ship a usable first slice, then iterate.

If you operate on AlayaCare and want referrals to create themselves, caregivers to be routed automatically, and families to get compliant updates, we have already built the pattern end-to-end. See our broader workflow automation services at /services#workflow-automation, read why rollouts fail in /blog/why-90-percent-of-automation-projects-fail, and when you are ready to scope your build, book a call at /book.