Skip to content

Developers

Connect to Ayulex HMIS over HL7 FHIR R4.

A read-only FHIR R4 interface for the systems around your hospital: analytics, registries, insurer and referral integrations. Each hospital issues, scopes and revokes its own keys.

Base URL
https://hmis.ayulex.com/api/fhir
FHIR version
R4 (4.0.1)
Format
application/fhir+json
Access
Read-only, one hospital per key
Authentication
Bearer API key, scope fhir:read

Authentication

One key per integration, issued by the hospital.

  1. 1

    An administrator opens Settings → Integrations, names the key, chooses the fhir:read scope and an expiry of up to two years.

  2. 2

    The key, which begins ayx_, is shown once. Ayulex stores only its SHA-256 hash, so a lost key is revoked and replaced, never recovered.

  3. 3

    Your system sends it as a bearer token over HTTPS. Each key reads only its own hospital's records.

Request: find a patient by UHID
curl "https://hmis.ayulex.com/api/fhir/Patient?identifier=urn:ayulex:uhid%7C24-018377" \
  -H "Authorization: Bearer ayx_••••••••••••••••" \
  -H "Accept: application/fhir+json"
Response: Patient (sample data)
{
  "resourceType": "Patient",
  "id": "3f6c2a9e-8b1d-4c7e-9a52-6d0e1f2b7c41",
  "identifier": [
    {
      "use": "usual",
      "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" }] },
      "system": "urn:ayulex:uhid",
      "value": "24-018377"
    },
    {
      "use": "official",
      "type": { "text": "ABHA number" },
      "system": "https://healthid.abdm.gov.in",
      "value": "91-1111-2222-3333"
    }
  ],
  "active": true,
  "name": [{ "use": "official", "text": "Sunita Devi", "family": "Devi", "given": ["Sunita"] }],
  "telecom": [{ "system": "phone", "value": "+919800000000", "use": "mobile" }],
  "gender": "female",
  "birthDate": "1974-03-12",
  "address": [{ "use": "home", "city": "Aizawl", "state": "Mizoram", "postalCode": "796001", "country": "IN" }]
}

Resources

What you can read.

Paths are relative to the base URL. Identifiers are opaque; take them from a search result or a reference in another resource.

CapabilityStatement

  • GET /metadata

What this server supports. Public: no key needed.

Patient

  • GET /Patient/{id}
  • GET /Patient?identifier={system}|{value}
  • GET /Patient?telecom={phone}

Search by UHID (system urn:ayulex:uhid), by ABHA number or address (system https://healthid.abdm.gov.in), or by phone. Up to 20 matches in a searchset Bundle.

Encounter

  • GET /Encounter/{id}

Class (ambulatory, inpatient, emergency or virtual), status, period, reason and diagnoses coded in ICD-10, ICD-10-CM, ICD-11 or SNOMED CT.

MedicationRequest

  • GET /MedicationRequest/{prescriptionId}
  • GET /MedicationRequest/{prescriptionId}-{n}

One resource per prescribed medicine, with dose, frequency, route and duration. A bare prescription id returns all its lines as a collection Bundle.

Observation

  • GET /Observation/{vitalsId}
  • GET /Observation/{vitalsId}-{bp|hr|rr|spo2|temp|weight|height|bmi}

Vital signs coded in LOINC with UCUM units; blood pressure as a panel with systolic and diastolic components. A bare vitals id returns the whole set.

Errors

Every error is an OperationOutcome.

HTTPCodeWhen
400invalidThe request is malformed, for example a Patient search without identifier or telecom.
401securityThe key is missing, unknown, revoked or expired, or the hospital's account is suspended.
403securityThe key does not carry the fhir:read scope.
404not-foundNo such record in this hospital, or the patient is restricted.
429throttledThe key has made more than 600 requests in the current minute.
Example: 401
{
  "resourceType": "OperationOutcome",
  "issue": [{ "severity": "error", "code": "security", "diagnostics": "Invalid or expired API key." }]
}

Privacy and audit

Integrations are held to the same rules as staff.

  • Every record released through the API is written to the hospital's audit trail, with the key that read it.
  • Restricted patients are never released to an integration: they read as not found.
  • Keys stop working the moment an administrator revokes them, when they expire, or if the hospital's account is suspended.
  • Administrators see each key's name, scope, expiry and when it was last used.

Not available yet

Writing records through the API, and ABDM health information exchange (milestones M2 and M3). Both build on this interface.

Building an integration? Write to support@ayulex.com.

Limits and versions

What to build against.

Rate limit
600 requests a minute per key. Over that, requests get 429 until the next minute begins.
Version
FHIR R4 (4.0.1), read-only. Every change so far has added to responses without removing anything.
Description
OpenAPI 3.1 file for code generators and API tools. /developers/openapi.json
Sandbox
There is no public test key yet.

Changelog

What changed, and when.

  1. Each key is limited to 600 requests a minute; going over returns 429 with an OperationOutcome coded throttled. OpenAPI description published.

  2. Encounter diagnoses carry ICD-11, ICD-10-CM and SNOMED CT codes as well as ICD-10.

  3. Restricted patients are never released to integrations; their records read as not found.

  4. First release: CapabilityStatement, Patient (read; search by UHID, ABHA or phone), Encounter, MedicationRequest and Observation (vital signs), with API keys scoped fhir:read.

See Ayulex HMIS on your own workflows.

Tell us about your hospital and we will tailor the demonstration to your departments, your tariffs and the way your teams work today.

Write to us

support@ayulex.com

We reply by e-mail.

TiLi Center, 2nd Floor, MV119 JL BuildingMission Veng, AizawlMizoram 796005, India

Already a customer? Sign in to your hospital