4. Integration Documentation

Global Clinic sits between patients, hospitals and a set of external service providers. This section documents the inbound integration surface the platform exposes and the outbound integrations it consumes. None of these are live in the reference build; this is the production design. Every integration follows the same cross-cutting rules in 4.3.

4.1 Inbound integrations

How external systems and partners send data into the platform.

REST APIs

The primary inbound surface is the public REST API in the API Guide. Partners (clinics, agents, employers) authenticate with OAuth 2.1 client credentials or a scoped API key, are tenant-scoped, and are rate-limited per the tiers in the API guide. All writes are idempotent.

Webhooks (inbound from providers)

External providers notify the platform of state changes by calling signed webhook endpoints:

Inbound webhooks are verified by HMAC signature and an idempotency key, processed asynchronously onto the event bus, and acknowledged quickly. Replays are safe because handlers are idempotent.

Event-driven integrations

Internally, domain events drive side effects (a confirmed milestone releases escrow; a visa grant notifies the patient and advances the stage). Events are published to a durable bus and consumed at-least-once by subscribers (Notifications, Reporting, Analytics). This decoupling means an external outage degrades gracefully rather than blocking the user.

flowchart LR
  SVC[Domain service] --> BUS[(Event bus)]
  BUS --> NOTIF[Notifications]
  BUS --> RPT[Reporting]
  BUS --> ANALYTICS[Analytics export]
  BUS --> CRM[CRM sync]

File-based imports

For partners without an API, the platform supports batch imports via secure file transfer (SFTP or signed object-storage upload):

• Clinic pricing and capacity as CSV or XLSX, validated against the schema, dry-run previewed, then applied.
• Bulk lead import from agent or campaign sources, attributed and de-duplicated.
• Reconciliation files from the payment partner, matched against the ledger.

Imports are validated row by row; rejects are reported with row and reason; partial success is recorded and auditable.

Partner integrations

Higher-touch partners (hospital groups, employers and insurers for the US segment, CRM systems) integrate through a combination of the REST API, webhooks and scheduled syncs, governed by a data-sharing agreement that fixes scope, residency and retention.

4.2 Outbound integrations

Providers the platform calls. Each entry states the integration purpose and the specifics required by the brief: authentication, request and response model, retry strategy, error handling, monitoring and security.

Travel providers (aggregator or GDS)

• Purpose: search and book multi-segment itineraries for a corridor and dates.
• Auth: OAuth 2.0 client credentials; per-environment client id and secret in the secrets manager.
• Models: request a search by origin, destination, dates and travellers; receive priced itineraries; book a selected itinerary and receive a PNR or booking reference.
• Retry: idempotent search with backoff; booking guarded by an idempotency key to avoid double-booking; reads retried up to a bounded count.
• Errors: map provider error codes to internal codes; on unavailability fall back to the manual Travel Desk path; never leave a patient without a next step.
• Monitoring: search latency, booking success rate, provider error rate; alert on booking failures.
• Security: PII minimised to what booking requires; responses stored encrypted; no card data touches the platform.

Airline booking providers

• Purpose: corridor-specific flight options and ticketing, including attendant travel.
• Auth: API key or OAuth per carrier or aggregator.
• Models: flight option (airline, flight number, depart and arrive, duration, stops, cabin, indicative fare, tags); booking confirmation with ticket reference.
• Retry / errors / monitoring / security: as travel providers; fare changes between search and book are revalidated before ticketing.

Hotel booking providers

• Purpose: attendant-friendly accommodation near the treating hospital.
• Auth: API key per provider.
• Models: stay option (name, kind, distance, rating, nightly rate, tags such as attendant bed and halal kitchen); booking confirmation.
• Retry: availability re-checked before confirmation; idempotent booking.
• Errors: on unavailability, propose an equivalent and rebook via the Travel Desk.
• Monitoring: availability hit rate, booking success; Security: guest PII minimised and encrypted.

Visa service providers and government channels

• Purpose: drive the e-Medical Visa and e-Medical Attendant Visa applications and track status; generate invitation letters.
• Auth: government or intermediary credentials; where no API exists, a structured manual operations process.
• Models: application package (corridor Country Pack documents and fields), submission acknowledgement with a medical reference number, status updates to grant or rejection.
• Retry: submission idempotent; status polled or received by webhook.
• Errors: rejection routes to the visa exception playbook (correct and resubmit, alternative route, or refund); a missing API is handled by the manual fallback.
• Monitoring: submission success, processing time per corridor, rejection rate; alert on SLA breach.
• Security: identity and financial documents transmitted over encrypted channels with strict access logging; data residency per Country Pack.

Payment gateways and escrow / trust-account partner

• Purpose: collect funds, hold them in escrow, release on verified milestones, and refund.
• Auth: secret API key plus signed webhooks; least-privilege keys per environment.
• Models: payment intent (amount minor unit, currency, method), escrow account, milestone release, refund; all reconciled to the internal append-only ledger.
• Retry: all money operations carry an idempotency key; releases and refunds are exactly-once at the ledger even if retried.
• Errors: payment failure returns a safe, non-charging error; partial capture is never allowed; disputes place the tranche on hold.
• Monitoring: fund success rate, release latency, refund SLA, reconciliation breaks; alert on any reconciliation mismatch.
• Security: the platform is not in the card-data path (the gateway is); PCI scope is minimised; multi-currency per corridor; AML and sanctions screening before funding on enhanced-risk corridors.

Communication providers (Email, SMS, WhatsApp)

• Purpose: omnichannel delivery of notifications and messages, prioritising WhatsApp in target corridors.
• Auth: provider API key; sender identities verified.
• Models: templated message send with channel, recipient, locale and variables; delivery and read receipts via webhook.
• Retry: send retried with backoff; channel fallback (for example WhatsApp to SMS) on failure.
• Errors: undeliverable addresses flagged; opt-out respected.
• Monitoring: delivery and read rates per channel and corridor; alert on delivery collapse.
• Security: message content minimised; consent and opt-out enforced; no sensitive clinical detail in unencrypted channels.

Translation services

• Purpose: interpreter and document translation for non-English corridors.
• Auth: API key.
• Models: text or document translation request with source and target locale; on-call human interpreter scheduling.
• Retry / errors: machine translation retried; clinical conversations use a human interpreter, never machine-only.
• Monitoring: turnaround time; Security: clinical text handled under the same PII rules; no retention by the provider beyond the request.

Insurance providers

• Purpose: pre-authorisation, claim documentation, and US employer or insurer medical-travel arrangements.
• Auth: partner-specific (OAuth or mTLS).
• Models: eligibility and pre-authorisation request and response; claim-ready itemised invoice export.
• Retry / errors: eligibility retried; failures fall back to self-pay with claim-ready documentation.
• Monitoring: pre-auth turnaround; Security: HIPAA-aligned handling for US data, Business Associate Agreement where applicable.

CRM platforms

• Purpose: sync leads, cases and conversion events into the marketing and sales CRM.
• Auth: OAuth or API key.
• Models: contact, lead, opportunity and case-stage events; bi-directional where the CRM owns campaign attribution.
• Retry: event sync retried; conflicts resolved by last-writer with audit.
• Monitoring: sync lag and error rate; Security: only non-clinical marketing fields are synced; clinical data stays in the platform.

Analytics platforms

• Purpose: product and funnel analytics, attribution, and SLA and conversion dashboards.
• Auth: write key; server-side export preferred over client tags for sensitive surfaces.
• Models: event stream (funnel by corridor and channel, affiliate attribution, outcomes) exported to the warehouse.
• Retry: buffered, at-least-once export.
• Monitoring: export freshness; Security: events are pseudonymised; no raw PII or clinical detail leaves the platform.

4.3 Cross-cutting integration rules

These apply to every integration, inbound and outbound:

1. Authentication. Credentials live only in the secrets manager, are least-privilege and per-environment, and are rotated. Nothing is in source or the static bundle.
2. Idempotency. Every create and money or booking operation carries an idempotency key; retries never duplicate.
3. Retry and backoff. Transient failures retry with exponential backoff and jitter up to a bounded count, then surface a typed error.
4. Circuit breaking and fallback. A failing provider trips a breaker and routes to the manual operations fallback so the patient is never stuck.
5. Error mapping. Provider errors map to internal error codes; user-facing messages are safe and actionable.
6. Monitoring. Each integration emits latency, success rate and error rate; SLOs and alerts cover money, visa and travel paths.
7. Security and data minimisation. Send only the data the provider needs; encrypt in transit; respect corridor data residency; log every exchange for audit.
8. Contracts and versioning. Integrations are versioned; provider changes are absorbed behind an internal adapter so domain services are insulated.

flowchart LR
  SVC[Domain service] --> ADP[Provider adapter]
  ADP --> CB{Circuit breaker}
  CB -- closed --> PROV[External provider]
  CB -- open --> FB[Manual ops fallback]
  PROV --> ADP
  ADP --> AUD[(Audit + metrics)]