claudetools/.claude/skills/alis/references/api-reference.md

ALIS API Reference (for the alis skill)

Source of truth: the live Swagger specs the ALIS API publishes.

• Swagger UI: https://api.alisonline.com/index.html
• Raw specs: https://api.alisonline.com/specs/v1/openapi.json (also v2, v3)
• Vendor docs (gated, requires support login): https://support.alisonline.com/

ALIS = Medtelligent's assisted-living EHR. The API is a partner/App-Store integration API. A tenant lives at <tenant>.alisonline.com (e.g. cascadestucson.alisonline.com) but all API traffic goes to the shared host api.alisonline.com, scoped by the logged-in user's company + a communityId.

Spec sizes at build (2026-06-29): v1 = 139 paths (main surface), v2 = 14 (newer streaming exports + incidents), v3 = 5 (streaming exports). Tags: User (auth), Admin, Export:, Integration: (Billing/Care/Communities/Residents/Staff/Prospects/Incidents/Hooks/App Specific), Pharmacy.

Authentication

Global security is an OR list: Bearer | BasicAuth | VendorKey — any one authorizes.

• Bearer (what this skill uses):
  • POST /user/tokens body {"username":"<user>@<tenantKey>","password":"..."} → { accessToken (JWT, expiresIn 3600), refreshToken }
  • POST /user/tokens/refresh body {accessToken, refreshToken} → new pair
  • Send Authorization: Bearer <accessToken> on every call.
  • The username MUST be tenant-qualified. howard.enos → HTTP 400 (Username must match ^<username>@<tenantKey>$); howard.enos@cascadestucson → 200. tenantKey = the tenant subdomain (cascadestucson).
• VendorKey: X-Vendor-Key: <key> header — issued by Medtelligent when an App-Store app is installed (per-client creds). Not required when a user JWT is used.
• BasicAuth: Authorization: Basic ... — the existing clients/cascades-tucson/alis-api-microsoft-basic vault entry is this style (used by Microsoft to call ALIS).

Staff endpoints — READ ONLY (this is the key constraint)

There is no POST/PUT/PATCH/DELETE for staff anywhere in v1/v2/v3. All six are GET:

Method	Path	Returns
GET	/v1/integration/staff?communityId={id}	roster (communityId REQUIRED — omitting → 403 "Not authorized for facility 0")
GET	/v1/integration/staff/{staffId}	one staff member
GET	/v1/integration/staff/{staffId}/basicInfo	address, license, jobRole, securityRoles
GET	/v1/integration/staff/{staffId}/photo	photo
GET	/v1/export/staff	bulk export
GET	/v1/export/staff/complianceDetails	training/compliance

Staff list record fields: staffId, companyTextKey, communityId, firstName, lastName, nickName, staffRecordNumber, mobilePhoneNumber, primaryEmail, dateOfBirth, status, hireDate, dischargeDate, hasPhoto, jobRole, securityRoles[].

Optional query params on the list: status, includeAssociatedStaff.

To CHANGE staff → there is no API. Use the ALIS web UI Staff → Import with the 13-column .xls (see import_builder.py / SKILL.md). That import sets Login Enabled and Password, i.e. it is also how staff logins are provisioned.

Other write surfaces (out of scope for this skill, but available on the JWT)

The API does allow writes for non-staff objects, e.g.:

• Residents: POST /v1/integration/residents (create), POST .../{residentId}/basicInfo, contacts, photo, observations, vitals, room assignments, diagnoses, monitoring flags.
• Prospects (CRM): POST/PUT /v1/integration/prospects...
• Billing: incidental charges, payments, statements.
• Webhooks: /v1/integration/hooks (subscribe to object create/modify events).

Scope observed (Cascades, communityId 622, build 2026-06-29)

• 1 community: 622 = "Cascades of Tucson".
• 612 staff total (504 Discharged, 107 Hired, 1 Observer).
• 23 distinct Security Roles in use; 74 distinct Job Role strings (free text — includes typos/dupes like caregiver vs Certified Caregiver, and junk like Test, Dead Weight — treat Job Role as free text, Security Roles as the controlled list).
• See role-map.json for the snapshot + job-role → security-role mapping.