A lightweight integration specification covering the FHIR R4 endpoints Travi consumes and exposes, authentication flow, webhook contracts, and a self-assessment checklist for hospital IT teams evaluating integration complexity.
Travi registers as a SMART on FHIR app in the hospital's EHR App Gallery. OAuth 2.0 authorization code flow with PKCE. Scopes requested: patient/*.read, user/Task.write, user/Communication.write, user/ClinicalImpression.write.
All Travi API endpoints require a signed JWT bearer token. Tokens are scoped per hospital, expire in 1 hour, and are rotated automatically. Hospital IT teams receive a client ID and client secret during onboarding — no API keys are shared with clinical staff.
For hospitals that require it, Travi supports mTLS on the FHIR ingest endpoint. The hospital provides a client certificate during onboarding; Travi pins the certificate and rejects connections from any other source.
| FHIR Resource | Trigger | Key Fields Used | Required |
|---|---|---|---|
| Encounter | status = finished, class = IMP (inpatient) |
period.end, subject, hospitalization.dischargeDisposition | YES |
| Patient | Pulled on discharge event | name, telecom (phone), birthDate, address, language | YES |
| MedicationRequest | status = active, linked to Encounter |
medication.code, dosageInstruction, dispenseRequest.numberOfRepeatsAllowed | YES |
| DocumentReference | type = discharge summary (LOINC 18842-5) | content.attachment (base64 or URL), context.encounter | YES |
| Appointment | status = booked, linked to Patient |
start, end, participant, serviceType | OPTIONAL |
| Observation | category = vital-signs or laboratory, last 30 days | code (LOINC), valueQuantity, effectiveDateTime | OPTIONAL |
| Condition | clinicalStatus = active, linked to Patient |
code (ICD-10), severity, onsetDateTime | OPTIONAL |
| FHIR Resource | Purpose | Trigger | Frequency |
|---|---|---|---|
| Task | Care plan task status (completed, in-progress, failed) | Patient SMS response or daily batch | Daily or on event |
| Communication | Log of all patient-Travi SMS interactions | Each SMS sent or received | Real-time |
| ClinicalImpression | AI-generated risk assessment with score and rationale | Risk score threshold crossed or daily | Daily + on escalation |
| Flag | High-risk patient alert visible in EHR patient banner | Escalation engine fires | On escalation only |
Travi exposes a single inbound webhook endpoint for EHR systems that push rather than allow polling:
POST https://api.travi.ai/v1/fhir/webhook
Authorization: Bearer <hospital_jwt>
Content-Type: application/fhir+json
X-Travi-Signature: sha256=<hmac_signature>
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{ "resource": { "resourceType": "Encounter", ... } },
{ "resource": { "resourceType": "Patient", ... } }
]
}All webhook payloads are HMAC-SHA256 signed using the hospital's shared secret. Travi validates the signature before processing. Idempotency key: Encounter.id — duplicate discharge events for the same encounter are deduplicated automatically. Response: 202 Accepted within 200ms; processing is async.
| Endpoint | Returns | Auth |
|---|---|---|
| GET /v1/analytics/readmissions | 30-day readmission rate by cohort, DRG, and month | Hospital admin JWT |
| GET /v1/analytics/adherence | Medication fill rate, appointment attendance, task completion by cohort | Hospital admin JWT |
| GET /v1/analytics/hrrp | Projected HRRP penalty reduction and estimated dollar savings | Hospital admin JWT |
| GET /v1/analytics/tcm-billing | TCM-eligible encounters, billed vs. unbilled, CPT code breakdown | Hospital admin JWT |
| GET /v1/patients/{id}/timeline | Full 30-day task and interaction timeline for a single patient | Care coordinator JWT (own cohort only) |
Use this checklist to estimate integration complexity before the first call with Travi's integration team. All "YES" answers indicate a standard 6–8 week integration. Each "NO" adds 1–3 weeks.
Travi provides a dedicated integration engineer for every pilot and contract customer. The integration engineer handles SMART app registration, data mapping, UAT coordination, and go-live monitoring. A sandbox environment with synthetic patient data is available for testing before any production data is accessed. Full integration documentation is available under NDA.
See also: FHIR R4 Data Flow — architecture diagram showing how these resources move through the pipeline, and Security Architecture — for PHI handling and compliance details.