{ "openapi": "3.1.0", "info": { "title": "The Rail", "version": "0.1.0-draft", "description": "Every call on the rail, grouped by the stop that makes it — the same\norder the teaching pages follow.\n\n**These contracts are under review.** Paths and field names will change.\nUse this reference to see the shape of each call and to try it against the\nsandbox; take final field names from the signed-off spec.\n\nSet a token with **Set API Token** in the header to run any call below." }, "servers": [ { "url": "https://api-dev.slade360edi.com/orchestrator", "description": "Development" }, { "url": "https://api.slade360edi.com/orchestrator", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "00 · Authenticate", "description": "Calls made at Authenticate. Taught at /rail/stops/Authenticate." }, { "name": "01 · Identify", "description": "Calls made at Identify. Taught at /rail/stops/Identify." }, { "name": "02 · Verify cover", "description": "Calls made at Verify cover. Taught at /rail/stops/Entitle." }, { "name": "03 · Consent", "description": "Calls made at Consent. Taught at /rail/stops/Consent." }, { "name": "04 · Visit", "description": "Calls made at Visit. Taught at /rail/stops/Visit." }, { "name": "05 · Treat", "description": "Calls made at Treat. Taught at /rail/stops/Treat." }, { "name": "06 · Preauthorize", "description": "Calls made at Preauthorize. Taught at /rail/stops/Preauth." }, { "name": "07 · Bill", "description": "Calls made at Bill. Taught at /rail/stops/Bill." }, { "name": "08 · Submit", "description": "Calls made at Submit. Taught at /rail/stops/Submit." }, { "name": "09 · Reconcile", "description": "Calls made at Reconcile. Taught at /rail/stops/Reconcile." } ], "paths": { "/realms/slade360/protocol/openid-connect/token": { "post": { "tags": [ "00 · Authenticate" ], "operationId": "auth.token", "summary": "Exchange client credentials for an access token.", "description": "Exchange your `client_id` and `client_secret` for an access token using the `client_credentials` grant. Tokens expire after 30 minutes (`expires_in: 1800`) and no refresh token is issued — request a new token on expiry.\n\n**Keep from the response:** `access_token`\n\n**Taught in:** [00 · Authenticate](/rail/stops/Authenticate)", "responses": { "200": { "description": "Returns `access_token`." }, "401": { "description": "Invalid client or client credentials.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized_client" }, "error_description": { "type": "string", "example": "Invalid client or Invalid client credentials" } } } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "client_secret", "grant_type" ], "properties": { "client_id": { "type": "string", "description": "The client identifier issued to your integration.", "example": "your-client-id" }, "client_secret": { "type": "string", "description": "The client secret issued alongside the client_id.", "example": "your-client-secret" }, "grant_type": { "type": "string", "description": "Must be client_credentials.", "default": "client_credentials", "example": "client_credentials" } } } } } }, "servers": [ { "url": "https://identity-dev.slade360edi.com", "description": "Development" }, { "url": "https://identity.slade360edi.com", "description": "Production" } ], "security": [] } }, "/api/v1/callbacks": { "post": { "tags": [ "00 · Authenticate" ], "operationId": "callbacks.register", "summary": "Register webhook endpoints. Required before a claim may be submitted.", "description": "Register webhook endpoints. Required before a claim may be submitted.\n\n**Not implemented yet.** No /api/v1/callbacks route is registered in the service.\n\n**Keep from the response:** `callback_id`\n\n**Taught in:** [00 · Authenticate](/rail/stops/Authenticate)", "responses": { "200": { "description": "Returns `callback_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "example": "{{callback_url}}" }, "events": { "type": "array", "items": { "type": "string", "example": "preauth.decision" } }, "secret": { "type": "string", "example": "{{callback_secret}}" } } }, "example": { "url": "{{callback_url}}", "events": [ "preauth.decision", "claim.decision", "remittance.posted" ], "secret": "{{callback_secret}}" } } } } } }, "/api/v1/terminology/concepts": { "get": { "tags": [ "01 · Identify" ], "operationId": "identifier.types", "summary": "The document types a desk may choose from today. Cache by version; never embed.", "description": "The document types a desk may choose from today. Cache by version; never embed.\n\n**Keep from the response:** `codes[].code`\n\n**Taught in:** [01 · Identify](/rail/stops/Identify)", "parameters": [ { "name": "code_system", "in": "query", "required": true, "description": "code system", "schema": { "type": "string" }, "example": "IDENTIFIER-TYPES" }, { "name": "version", "in": "query", "required": true, "description": "version", "schema": { "type": "string" }, "example": "serving" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `codes[].code`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value_set": { "type": "string", "example": "identifier-types" }, "version": { "type": "string", "example": "2026-08-06.1" }, "codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "NATIONAL_ID" }, "status": { "type": "string", "example": "active" } } } } } }, "example": { "value_set": "identifier-types", "version": "2026-08-06.1", "codes": [ { "code": "NATIONAL_ID", "status": "active" }, { "code": "CR_NUMBER", "status": "active" }, { "code": "BIRTH_NOTIFICATION", "status": "active" }, { "code": "BIRTH_CERTIFICATE", "status": "active" }, { "code": "ALIEN_ID", "status": "active" }, { "code": "REFUGEE_ID", "status": "active" }, { "code": "MANDATE_NUMBER", "status": "active" }, { "code": "TEMPORARY_REGISTRATION", "status": "active" }, { "code": "PASSPORT", "status": "active" } ] } } } } } } }, "/api/v2/patients/lookup": { "post": { "tags": [ "01 · Identify" ], "operationId": "patient.lookup", "summary": "Resolve an identifier pair to one unique_patient_id, with masked details to confirm the human.", "description": "Resolve an identifier pair to one unique_patient_id, with masked details to confirm the human.\n\n**Keep from the response:** `unique_patient_id`\n\n**Taught in:** [01 · Identify](/rail/stops/Identify)", "parameters": [ { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `unique_patient_id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "lookup_ref": { "type": "string", "example": "LKP-2026-08-05-000512" }, "unique_patient_id": { "type": "string", "example": "SIL-UPI-0091774" }, "is_alive": { "type": "boolean", "example": true }, "biodata": { "type": "object", "properties": { "name": { "type": "string", "example": "Wanjiru M****i M****i" }, "date_of_birth": { "type": "string", "example": "2000-06-29" }, "gender": { "type": "string", "example": "MALE" }, "registered_on": { "type": "string", "example": "2024-10-09" } } }, "matched_on": { "type": "object", "properties": { "type": { "type": "string", "example": "NATIONAL_ID" }, "value": { "type": "string", "example": "3312****" } } }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "NATIONAL_ID" }, "value": { "type": "string", "example": "3312****" }, "verified": { "type": "boolean", "example": true } } } }, "contacts": { "type": "object", "properties": { "phones": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "+254700****848" }, "verified": { "type": "boolean", "example": true } } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "roy***@example.co.ke" }, "verified": { "type": "boolean", "example": false } } } } } }, "next_action": { "type": "object", "properties": { "type": { "type": "string", "example": "select_cover" }, "endpoint": { "type": "string", "example": "/api/v2/patients/SIL-UPI-0091774/covers" } } } } }, "example": { "lookup_ref": "LKP-2026-08-05-000512", "unique_patient_id": "SIL-UPI-0091774", "is_alive": true, "biodata": { "name": "Wanjiru M****i M****i", "date_of_birth": "2000-06-29", "gender": "MALE", "registered_on": "2024-10-09" }, "matched_on": { "type": "NATIONAL_ID", "value": "3312****" }, "identifiers": [ { "type": "NATIONAL_ID", "value": "3312****", "verified": true }, { "type": "CLIENT_REGISTRY_NO", "value": "CR61*************", "verified": true }, { "type": "SHA_NUMBER", "value": "SHA0*********", "verified": true } ], "contacts": { "phones": [ { "value": "+254700****848", "verified": true } ], "emails": [ { "value": "roy***@example.co.ke", "verified": false } ] }, "next_action": { "type": "select_cover", "endpoint": "/api/v2/patients/SIL-UPI-0091774/covers" } } } } }, "404": { "description": "The pair resolves to no record. Re-check the type before re-typing the number.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "MEMBER_NOT_FOUND" }, "message": { "type": "string", "example": "No record matches National ID 33121466." }, "path": { "type": "string", "example": "identifier.value" }, "fix_stage": { "type": "string", "example": "identify" } } }, "example": { "error": "MEMBER_NOT_FOUND", "message": "No record matches National ID 33121466.", "path": "identifier.value", "fix_stage": "identify" } } } }, "409": { "description": "More than one record matched. A prompt for a second document, not a failure to retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "IDENTIFIER_CONFLICT" }, "message": { "type": "string", "example": "National ID 33121466 matches 2 records. Ask for a second document." }, "path": { "type": "string", "example": "identifier.value" }, "fix_stage": { "type": "string", "example": "identify" }, "detail": { "type": "object", "properties": { "match_count": { "type": "number", "example": 2 }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "biodata": { "type": "object", "properties": { "name": { "type": "string", "example": "Wanjiru M****i M****i" }, "gender": { "type": "string", "example": "MALE" } } }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "CLIENT_REGISTRY_NO" }, "value": { "type": "string", "example": "CR61*************" } } } }, "contacts": { "type": "object", "properties": { "phones": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "+254700****848" }, "verified": { "type": "boolean", "example": true } } } } } } } } }, "disambiguate_with": { "type": "array", "items": { "type": "string", "example": "CLIENT_REGISTRY_NO" } } } } } }, "example": { "error": "IDENTIFIER_CONFLICT", "message": "National ID 33121466 matches 2 records. Ask for a second document.", "path": "identifier.value", "fix_stage": "identify", "detail": { "match_count": 2, "candidates": [ { "biodata": { "name": "Wanjiru M****i M****i", "gender": "MALE" }, "identifiers": [ { "type": "CLIENT_REGISTRY_NO", "value": "CR61*************" } ], "contacts": { "phones": [ { "value": "+254700****848", "verified": true } ] } }, { "biodata": { "name": "Wanjiru M****a K****u", "gender": "MALE" }, "identifiers": [ { "type": "CLIENT_REGISTRY_NO", "value": "CR77*************" } ], "contacts": { "phones": [] } } ], "disambiguate_with": [ "CLIENT_REGISTRY_NO", "PASSPORT_NO", "BIRTH_CERTIFICATE_NO" ] } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "object", "properties": { "type": { "type": "string", "example": "NATIONAL_ID" }, "value": { "type": "string", "example": "{{national_id}}" } } } } }, "example": { "identifier": { "type": "NATIONAL_ID", "value": "{{national_id}}" } } } } } } }, "/api/v1/professionals": { "get": { "tags": [ "01 · Identify" ], "operationId": "registry.practitioners", "summary": "Health worker registry — one practitioner, with a licence verdict you do not have to derive.", "description": "Health worker registry — one practitioner, with a licence verdict you do not have to derive.\n\n**Keep from the response:** `licence.status`\n\n**Taught in:** [01 · Identify](/rail/stops/Identify)", "parameters": [ { "name": "identification_number", "in": "query", "required": true, "description": "practitioner license", "schema": { "type": "string" }, "example": "" }, { "name": "identification_type", "in": "query", "required": true, "description": "identification type", "schema": { "type": "string" }, "example": "registration_number" }, { "name": "regulator", "in": "query", "required": true, "description": "regulator", "schema": { "type": "string" }, "example": "KMPDC" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `licence.status`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "registration_number": { "type": "string", "example": "A8***1" }, "name": { "type": "string", "example": "Dr J*** W*** M***" }, "regulator": { "type": "string", "example": "KMPDC" }, "licence": { "type": "object", "properties": { "status": { "type": "string", "example": "ACTIVE" }, "valid_to": { "type": "string", "example": "2027-03-31" }, "checked_at": { "type": "string", "example": "2026-08-13T09:41:02+03:00" } } }, "professional_details": { "type": "object", "properties": { "cadre": { "type": "string", "example": "Medical Practitioner" }, "specialty": { "type": "string", "example": "General Surgery" }, "discipline_name": { "type": "string", "example": "Surgery" } } }, "next_action": { "type": "object", "properties": { "type": { "type": "string", "example": "none" } } } } }, "example": { "registration_number": "A8***1", "name": "Dr J*** W*** M***", "regulator": "KMPDC", "licence": { "status": "ACTIVE", "valid_to": "2027-03-31", "checked_at": "2026-08-13T09:41:02+03:00" }, "professional_details": { "cadre": "Medical Practitioner", "specialty": "General Surgery", "discipline_name": "Surgery" }, "next_action": { "type": "none" } } } } }, "400": { "description": "A registration number without its regulator resolves to nothing — the same mistake as an identifier without its type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "REGULATOR_REQUIRED" }, "message": { "type": "string", "example": "regulator is required for a registration_number lookup. One of KMPDC, COC, NCK." }, "path": { "type": "string", "example": "regulator" }, "fix_stage": { "type": "string", "example": "identify" } } }, "example": { "error": "REGULATOR_REQUIRED", "message": "regulator is required for a registration_number lookup. One of KMPDC, COC, NCK.", "path": "regulator", "fix_stage": "identify" } } } }, "404": { "description": "No practitioner matches that pair.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "PRACTITIONER_NOT_FOUND" }, "message": { "type": "string", "example": "No practitioner registered as A81234 with KMPDC." }, "path": { "type": "string", "example": "identification_number" }, "fix_stage": { "type": "string", "example": "identify" } } }, "example": { "error": "PRACTITIONER_NOT_FOUND", "message": "No practitioner registered as A81234 with KMPDC.", "path": "identification_number", "fix_stage": "identify" } } } } } } }, "/api/v2/patients/{unique_patient_id}/covers": { "get": { "tags": [ "02 · Verify cover" ], "operationId": "covers.list", "summary": "Every cover usable by this member at this facility.", "description": "Every cover usable by this member at this facility.\n\n**Keep from the response:** `cover_id`\n\n**Taught in:** [02 · Verify cover](/rail/stops/Entitle)", "parameters": [ { "name": "unique_patient_id", "in": "path", "required": true, "description": "unique patient id", "schema": { "type": "string" }, "example": "" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `cover_id`." } } } }, "/api/v2/patients/{unique_patient_id}/covers/select": { "post": { "tags": [ "02 · Verify cover" ], "operationId": "covers.select", "summary": "Freeze a cover onto this encounter.", "description": "Freeze a cover onto this encounter.\n\n**Keep from the response:** `selection_ref`\n\n**Taught in:** [02 · Verify cover](/rail/stops/Entitle)", "parameters": [ { "name": "unique_patient_id", "in": "path", "required": true, "description": "unique patient id", "schema": { "type": "string" }, "example": "" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `selection_ref`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cover_id": { "type": "string", "example": "{{cover_id}}" }, "scheme_id": { "type": "string", "example": "{{scheme_id}}" }, "KMPDC_REG_NO": { "type": "string", "example": "{{facility_code}}" } } }, "example": { "cover_id": "{{cover_id}}", "scheme_id": "{{scheme_id}}", "KMPDC_REG_NO": "{{facility_code}}" } } } } } }, "/api/v2/patients/{unique_patient_id}/eligibility/{selection_ref}/benefits": { "get": { "tags": [ "02 · Verify cover" ], "operationId": "benefits.tree", "summary": "What the selected cover pays for. Call it with no parent_code for the top level, then pass the code you chose to descend one level, and repeat until nothing comes back.", "description": "What the selected cover pays for. Call it with no parent_code for the top level, then pass the code you chose to descend one level, and repeat until nothing comes back.\n\n**Keep from the response:** `benefit_code`\n\n**Taught in:** [02 · Verify cover](/rail/stops/Entitle)", "parameters": [ { "name": "unique_patient_id", "in": "path", "required": true, "description": "unique patient id", "schema": { "type": "string" }, "example": "" }, { "name": "selection_ref", "in": "path", "required": true, "description": "selection ref", "schema": { "type": "string" }, "example": "" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" }, { "name": "parent_code", "in": "query", "required": false, "description": "The code whose children to return. Omit it for the top level; pass a benefit code for the level below it, and so on down. Do not assume four levels.", "schema": { "type": "string" }, "example": "SHA-06" }, { "name": "search", "in": "query", "required": false, "description": "Filter this level by name or code.", "schema": { "type": "string" } }, { "name": "access_point", "in": "query", "required": false, "description": "Filter to what is payable at the access point of the current visit — outpatient, inpatient, and so on.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "required": false, "description": "Rows per page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns `benefit_code`." } } } }, "/api/v2/patients/{unique_patient_id}/authentications": { "post": { "tags": [ "03 · Consent" ], "operationId": "authentications.initiate", "summary": "Ask for an authentication. The rail decides and executes the factor; you get a resource back, and a URL to embed when the factor is one the member has to be present for.", "description": "Ask for an authentication. The rail decides and executes the factor; you get a resource back, and a URL to embed when the factor is one the member has to be present for.\n\n**Keep from the response:** `authentication_id, collection.url`\n\n**Taught in:** [03 · Consent](/rail/stops/Consent)", "parameters": [ { "name": "unique_patient_id", "in": "path", "required": true, "description": "unique patient id", "schema": { "type": "string" }, "example": "" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `authentication_id, collection.url`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authentication_id": { "type": "string", "example": "9f1c7c2e-6b3a-4a8d-9f2e-1a2b3c4d5e6f" }, "status": { "type": "string", "example": "pending" }, "next_action": { "type": "string", "example": "collect" }, "purpose": { "type": "string", "example": "visit_start" }, "network": { "type": "string", "example": "SHA" }, "collection": { "type": "object", "properties": { "url": { "type": "string", "example": "https://rail.savannahghi.org/orchestrator/api/v1/ui/launch?code=1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" } } }, "expires_at": { "type": "string", "example": "2026-09-02T14:35:00Z" } } }, "example": { "authentication_id": "9f1c7c2e-6b3a-4a8d-9f2e-1a2b3c4d5e6f", "status": "pending", "next_action": "collect", "purpose": "visit_start", "network": "SHA", "collection": { "url": "https://rail.savannahghi.org/orchestrator/api/v1/ui/launch?code=1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" }, "expires_at": "2026-09-02T14:35:00Z" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "network": { "type": "string", "example": "{{network}}" }, "purpose": { "type": "string", "example": "visit_start" }, "agent_id": { "type": "string", "example": "{{agent_national_id}}" }, "callback_url": { "type": "string", "example": "{{callback_url}}" }, "selection_ref": { "type": "string", "example": "{{selection_ref}}" } } }, "example": { "network": "{{network}}", "purpose": "visit_start", "agent_id": "{{agent_national_id}}", "callback_url": "{{callback_url}}", "selection_ref": "{{selection_ref}}" } } } } } }, "/api/v2/patients/{unique_patient_id}/authentications/{authentication_id}": { "get": { "tags": [ "03 · Consent" ], "operationId": "authentications.get", "summary": "Read the authentication. Poll this as the safety net; the callback is the primary path.", "description": "Read the authentication. Poll this as the safety net; the callback is the primary path.\n\n**Keep from the response:** `status, expires_at`\n\n**Taught in:** [03 · Consent](/rail/stops/Consent)", "parameters": [ { "name": "unique_patient_id", "in": "path", "required": true, "description": "unique patient id", "schema": { "type": "string" }, "example": "" }, { "name": "authentication_id", "in": "path", "required": true, "description": "authentication id", "schema": { "type": "string" }, "example": "" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `status, expires_at`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authentication_id": { "type": "string", "example": "9f1c7c2e-6b3a-4a8d-9f2e-1a2b3c4d5e6f" }, "status": { "type": "string", "example": "verified" }, "factor": { "type": "string", "example": "biometric" }, "purpose": { "type": "string", "example": "visit_start" }, "network": { "type": "string", "example": "SHA" }, "verified_at": { "type": "string", "example": "2026-09-02T14:33:12Z" }, "expires_at": { "type": "string", "example": "2026-09-02T14:43:12Z" } } }, "example": { "authentication_id": "9f1c7c2e-6b3a-4a8d-9f2e-1a2b3c4d5e6f", "status": "verified", "factor": "biometric", "purpose": "visit_start", "network": "SHA", "verified_at": "2026-09-02T14:33:12Z", "expires_at": "2026-09-02T14:43:12Z" } } } } } } }, "/api/v1/ui/consent/otp/send": { "post": { "tags": [ "03 · Consent" ], "operationId": "consent.otp.send", "summary": "Send the passcode for the launched authentication. Part of the hosted surface: a form post that answers with an HTML fragment, not JSON. Every field is required — the surface re-runs the consent decision on each swap, so the launch context travels with each post.", "description": "Send the passcode for the launched authentication. Part of the hosted surface: a form post that answers with an HTML fragment, not JSON. Every field is required — the surface re-runs the consent decision on each swap, so the launch context travels with each post.\n\n**Keep from the response:** `the re-rendered verify slot`\n\n**Taught in:** [03 · Consent](/rail/stops/Consent)", "parameters": [ { "name": "X-Csrf-Token", "in": "header", "required": true, "description": "The value of the hie_csrf cookie, echoed back. Without it the surface answers 403. The hie_session and hie_csrf cookies are minted by GET /api/v1/ui/launch and are scoped to the UI mount path, gateway prefix included.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An HTML fragment, swapped into the surface by htmx. Failures come back 200 as well, with the message inside the fragment, so a caller driving this directly cannot branch on the status code.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "authentication_id": { "type": "string", "example": "{{authentication_id}}" }, "contact_id": { "type": "string", "example": "{{contact_id}}" }, "unique_patient_id": { "type": "string", "example": "{{unique_patient_id}}" }, "purpose": { "type": "string", "example": "visit_start" }, "selection_ref": { "type": "string", "example": "{{selection_ref}}" }, "callback_url": { "type": "string", "example": "{{callback_url}}" } } }, "example": { "authentication_id": "{{authentication_id}}", "contact_id": "{{contact_id}}", "unique_patient_id": "{{unique_patient_id}}", "purpose": "visit_start", "selection_ref": "{{selection_ref}}", "callback_url": "{{callback_url}}" } } } } } }, "/api/v1/ui/consent/otp/verify": { "post": { "tags": [ "03 · Consent" ], "operationId": "consent.otp.verify", "summary": "Check the passcode the member read back. Answers with the receipt fragment on success, and with the executor's own message on a refusal.", "description": "Check the passcode the member read back. Answers with the receipt fragment on success, and with the executor's own message on a refusal.\n\n**Keep from the response:** `the receipt fragment`\n\n**Taught in:** [03 · Consent](/rail/stops/Consent)", "parameters": [ { "name": "X-Csrf-Token", "in": "header", "required": true, "description": "The value of the hie_csrf cookie, echoed back. Without it the surface answers 403. The hie_session and hie_csrf cookies are minted by GET /api/v1/ui/launch and are scoped to the UI mount path, gateway prefix included.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An HTML fragment, swapped into the surface by htmx. Failures come back 200 as well, with the message inside the fragment, so a caller driving this directly cannot branch on the status code.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "authentication_id": { "type": "string", "example": "{{authentication_id}}" }, "contact_id": { "type": "string", "example": "{{contact_id}}" }, "unique_patient_id": { "type": "string", "example": "{{unique_patient_id}}" }, "purpose": { "type": "string", "example": "visit_start" }, "selection_ref": { "type": "string", "example": "{{selection_ref}}" }, "callback_url": { "type": "string", "example": "{{callback_url}}" }, "otp": { "type": "string", "example": "{{otp}}" } } }, "example": { "authentication_id": "{{authentication_id}}", "contact_id": "{{contact_id}}", "unique_patient_id": "{{unique_patient_id}}", "purpose": "visit_start", "selection_ref": "{{selection_ref}}", "callback_url": "{{callback_url}}", "otp": "{{otp}}" } } } } } }, "/api/v2/visits": { "post": { "tags": [ "04 · Visit" ], "operationId": "visit.open", "summary": "Open a visit — an encounter and its account, in one atomic write. No payer is called; a visit with no service_lines is purely clinical.", "description": "Open a visit — an encounter and its account, in one atomic write. No payer is called; a visit with no service_lines is purely clinical.\n\n**Keep from the response:** `visit_ref`\n\n**Taught in:** [04 · Visit](/rail/stops/Visit)", "responses": { "200": { "description": "Returns `visit_ref`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unique_patient_id": { "type": "string", "example": "{{unique_patient_id}}" }, "service_type": { "type": "string", "example": "OUTPATIENT" }, "selection_ref": { "type": "string", "example": "{{selection_ref}}" }, "consent_ref": { "type": "string", "example": "{{consent_ref}}" }, "service_lines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "{{intervention_code}}" }, "cover": { "type": "string", "example": "{{cover_id}}" } } } } } }, "example": { "unique_patient_id": "{{unique_patient_id}}", "service_type": "OUTPATIENT", "selection_ref": "{{selection_ref}}", "consent_ref": "{{consent_ref}}", "service_lines": [ { "code": "{{intervention_code}}", "cover": "{{cover_id}}" } ] } } } } } }, "/api/v2/visits/{visit_ref}/service-lines": { "post": { "tags": [ "04 · Visit" ], "operationId": "serviceline.add", "summary": "Authorise a cover for a named intervention — the authorization unit. Payer-first: pending, then authorized or refused.", "description": "Authorise a cover for a named intervention — the authorization unit. Payer-first: pending, then authorized or refused.\n\n**Keep from the response:** `service_line_ref`\n\n**Taught in:** [04 · Visit](/rail/stops/Visit)", "parameters": [ { "name": "visit_ref", "in": "path", "required": true, "description": "visit ref", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `service_line_ref`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "{{intervention_code}}" }, "cover": { "type": "string", "example": "{{cover_id}}" } } }, "example": { "code": "{{intervention_code}}", "cover": "{{cover_id}}" } } } } } }, "/api/v2/visits/{visit_ref}/practitioners": { "post": { "tags": [ "04 · Visit" ], "operationId": "practitioner.add", "summary": "Record a practitioner on the visit, validated against the Health Worker Registry under its regulator before it is stored.", "description": "Record a practitioner on the visit, validated against the Health Worker Registry under its regulator before it is stored.\n\n**Keep from the response:** `practitioner_ref`\n\n**Taught in:** [04 · Visit](/rail/stops/Visit)", "parameters": [ { "name": "visit_ref", "in": "path", "required": true, "description": "visit ref", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `practitioner_ref`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "{{practitioner_reg_no}}" }, "id_type": { "type": "string", "example": "registration_number" }, "regulation_body": { "type": "string", "example": "{{regulation_body}}" }, "role": { "type": "string", "example": "attending" } } }, "example": { "id": "{{practitioner_reg_no}}", "id_type": "registration_number", "regulation_body": "{{regulation_body}}", "role": "attending" } } } } } }, "/api/v2/clinical/diagnoses": { "get": { "tags": [ "05 · Treat" ], "operationId": "diagnosis.search", "summary": "Search ICD-11 for a codable diagnosis. The picker is fetched, never typed.", "description": "Search ICD-11 for a codable diagnosis. The picker is fetched, never typed.\n\n**Not implemented yet.** Not registered. The live coded-list surface is /api/v1/terminology — /concepts, /concepts/{concept_id} and /value-sets — which is where an ICD-11 search will resolve from.\n\n**Keep from the response:** `codes[].code`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "version", "in": "query", "required": true, "description": "version", "schema": { "type": "string" }, "example": "serving" }, { "name": "q", "in": "query", "required": true, "description": "diagnosis query", "schema": { "type": "string" }, "example": "" }, { "name": "X-Facility-Id", "in": "header", "required": true, "description": "The facility this call is made from.", "schema": { "type": "string" }, "example": "{{facility_code}}" }, { "name": "X-Facility-Id-Type", "in": "header", "required": true, "description": "How to read X-Facility-Id: mfl, license-number, fr-code, registration-number or fid.", "schema": { "type": "string" }, "example": "fr-code" } ], "responses": { "200": { "description": "Returns `codes[].code`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value_set": { "type": "string", "example": "icd-11" }, "version": { "type": "string", "example": "2026-08-06.1" }, "codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "1F41" }, "display": { "type": "string", "example": "Plasmodium falciparum malaria" }, "status": { "type": "string", "example": "active" }, "codable": { "type": "boolean", "example": true } } } } } }, "example": { "value_set": "icd-11", "version": "2026-08-06.1", "codes": [ { "code": "1F41", "display": "Plasmodium falciparum malaria", "status": "active", "codable": true }, { "code": "1F40", "display": "Malaria due to Plasmodium falciparum", "status": "active", "codable": true } ] } } } } } } }, "/api/v2/visits/{visit_ref}/diagnoses": { "post": { "tags": [ "05 · Treat" ], "operationId": "diagnosis.record", "summary": "Record a diagnosis on the visit's clinical record — a Condition on the encounter. A clinical fact first; no cover appears here.", "description": "Record a diagnosis on the visit's clinical record — a Condition on the encounter. A clinical fact first; no cover appears here.\n\n**Keep from the response:** `diagnosis_ref`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_ref", "in": "path", "required": true, "description": "visit ref", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `diagnosis_ref`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "system": { "type": "string", "example": "ICD-11" }, "code": { "type": "string", "example": "CA40.Z" }, "role": { "type": "string", "example": "final" } } }, "example": { "system": "ICD-11", "code": "CA40.Z", "role": "final" } } } } } }, "/api/v1/visits/{visit_id}/diagnoses": { "get": { "tags": [ "05 · Treat" ], "operationId": "diagnosis.list", "summary": "Every diagnosis on this visit, and which intervention each one supports.", "description": "Every diagnosis on this visit, and which intervention each one supports.\n\n**Not implemented yet.** No diagnosis routes under a v1 visit. Writing one is live at POST /api/v2/visits/{visit_ref}/diagnoses; reading them back and withdrawing one are not.\n\n**Keep from the response:** `diagnoses[].diagnosis_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `diagnoses[].diagnosis_id`." } } } }, "/api/v1/visits/{visit_id}/diagnoses/{diagnosis_id}": { "delete": { "tags": [ "05 · Treat" ], "operationId": "diagnosis.remove", "summary": "Withdraw a diagnosis recorded in error. Refused once the claim is submitted.", "description": "Withdraw a diagnosis recorded in error. Refused once the claim is submitted.\n\n**Not implemented yet.** No diagnosis routes under a v1 visit. The nearest registered withdrawal is PATCH /api/v1/claims/diagnoses, which acts on a claim rather than on a visit.\n\n**Keep from the response:** `status`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" }, { "name": "diagnosis_id", "in": "path", "required": true, "description": "diagnosis id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `status`." } } } }, "/api/v1/visits/{visit_id}/clinical": { "post": { "tags": [ "05 · Treat" ], "operationId": "clinical.contribute", "summary": "Contribute the encounter to the shared health record as a FHIR bundle.", "description": "Contribute the encounter to the shared health record as a FHIR bundle.\n\n**Not implemented yet.** There is no /clinical child under a visit, and the registered visits group is v2, not v1. The nearest live calls are POST /api/v2/visits/{visit_ref}/diagnoses and the /api/v1/shr group — neither is a drop-in.\n\n**Keep from the response:** `bundle_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `bundle_id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle_id": { "type": "string", "example": "BDL-2026-08-14-004417" }, "status": { "type": "string", "example": "written" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "example": "Encounter" }, "id": { "type": "string", "example": "enc-9d21" }, "status": { "type": "string", "example": "written" } } } } } }, "example": { "bundle_id": "BDL-2026-08-14-004417", "status": "written", "resources": [ { "resourceType": "Encounter", "id": "enc-9d21", "status": "written" }, { "resourceType": "Condition", "id": "con-4a77", "status": "written" }, { "resourceType": "Observation", "id": "obs-11c3", "status": "written" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_type": { "type": "string", "example": "Bundle" }, "type": { "type": "string", "example": "transaction" }, "entry": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "object", "properties": { "resourceType": { "type": "string", "example": "Encounter" }, "status": { "type": "string", "example": "in-progress" }, "class": { "type": "object", "properties": { "code": { "type": "string", "example": "AMB" }, "display": { "type": "string", "example": "outpatient" } } } } } } } } } }, "example": { "resource_type": "Bundle", "type": "transaction", "entry": [ { "resource": { "resourceType": "Encounter", "status": "in-progress", "class": { "code": "AMB", "display": "outpatient" } } }, { "resource": { "resourceType": "Condition", "code": { "coding": [ { "system": "http://id.who.int/icd/release/11/mms", "code": "1F41" } ] } } }, { "resource": { "resourceType": "Observation", "code": { "coding": [ { "system": "http://loinc.org", "code": "8310-5" } ] }, "valueQuantity": { "value": 38.9, "unit": "Cel" } } } ] } } } } }, "get": { "tags": [ "05 · Treat" ], "operationId": "clinical.read", "summary": "Read back what this visit has written — the encounter and every resource under it.", "description": "Read back what this visit has written — the encounter and every resource under it.\n\n**Not implemented yet.** Same route as clinical.contribute, and equally unregistered. GET /api/v2/visits/{visit_ref}/documents reads what is attached to a visit; it is not a clinical read.\n\n**Keep from the response:** `resources[].id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `resources[].id`." } } } }, "/api/v1/clinical/episodes-of-care": { "get": { "tags": [ "05 · Treat" ], "operationId": "episodes.list", "summary": "The episodes of care this patient has open — the thread visits hang from.", "description": "The episodes of care this patient has open — the thread visits hang from.\n\n**Keep from the response:** `episode_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "responses": { "200": { "description": "Returns `episode_id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "episodes": { "type": "array", "items": { "type": "object", "properties": { "episode_id": { "type": "string", "example": "EPI-2026-05-02-000118" }, "condition": { "type": "object", "properties": { "icd11_code": { "type": "string", "example": "5A11" }, "display": { "type": "string", "example": "Type 2 diabetes mellitus" } } }, "status": { "type": "string", "example": "active" }, "opened_on": { "type": "string", "example": "2026-05-02" }, "managing_facility": { "type": "string", "example": "FR-14082" }, "encounter_count": { "type": "number", "example": 7 } } } } } }, "example": { "episodes": [ { "episode_id": "EPI-2026-05-02-000118", "condition": { "icd11_code": "5A11", "display": "Type 2 diabetes mellitus" }, "status": "active", "opened_on": "2026-05-02", "managing_facility": "FR-14082", "encounter_count": 7 } ] } } } } } }, "post": { "tags": [ "05 · Treat" ], "operationId": "episodes.open", "summary": "Open an episode, or attach this visit to one that is already running.", "description": "Open an episode, or attach this visit to one that is already running.\n\n**Keep from the response:** `episode_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "responses": { "200": { "description": "Returns `episode_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unique_patient_id": { "type": "string", "example": "{{unique_patient_id}}" }, "visit_id": { "type": "string", "example": "{{visit_id}}" }, "condition": { "type": "object", "properties": { "icd11_code": { "type": "string", "example": "5A11" } } }, "intent": { "type": "string", "example": "attach" } } }, "example": { "unique_patient_id": "{{unique_patient_id}}", "visit_id": "{{visit_id}}", "condition": { "icd11_code": "5A11" }, "intent": "attach" } } } } } }, "/api/v1/visits/{visit_id}/orders": { "post": { "tags": [ "05 · Treat" ], "operationId": "orders.create", "summary": "Order a lab, an image or a procedure. Routed to the performer, whether or not it is you.", "description": "Order a lab, an image or a procedure. Routed to the performer, whether or not it is you.\n\n**Not implemented yet.** No /orders prefix exists under either version, and no orders domain in the service.\n\n**Keep from the response:** `order_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `order_id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "example": "ORD-2026-08-14-002215" }, "status": { "type": "string", "example": "routed" }, "performer_facility": { "type": "string", "example": "FR-14082" }, "expanded_parameters": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "718-7" }, "display": { "type": "string", "example": "Haemoglobin" } } } } } }, "example": { "order_id": "ORD-2026-08-14-002215", "status": "routed", "performer_facility": "FR-14082", "expanded_parameters": [ { "code": "718-7", "display": "Haemoglobin" }, { "code": "789-8", "display": "Erythrocytes" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "example": "laboratory" }, "code": { "type": "object", "properties": { "system": { "type": "string", "example": "LOINC" }, "code": { "type": "string", "example": "24312-6" }, "display": { "type": "string", "example": "MRI Knee" } } }, "priority": { "type": "string", "example": "routine" }, "reason": { "type": "array", "items": { "type": "object", "properties": { "icd11_code": { "type": "string", "example": "1F41" } } } }, "requester": { "type": "object", "properties": { "hwr_number": { "type": "string", "example": "{{hwr_number}}" } } }, "performer_facility": { "type": "string", "example": "{{facility_code}}" }, "specimen": { "type": "object", "properties": { "type": { "type": "string", "example": "BLD" }, "collected_at": { "type": "string", "example": "2026-08-14T09:12:00+03:00" } } } } }, "example": { "category": "laboratory", "code": { "system": "LOINC", "code": "24312-6", "display": "MRI Knee" }, "priority": "routine", "reason": [ { "icd11_code": "1F41" } ], "requester": { "hwr_number": "{{hwr_number}}" }, "performer_facility": "{{facility_code}}", "specimen": { "type": "BLD", "collected_at": "2026-08-14T09:12:00+03:00" } } } } } } }, "/api/v1/orders": { "get": { "tags": [ "05 · Treat" ], "operationId": "orders.inbox", "summary": "Orders routed to this facility from anywhere on the rail — your work queue.", "description": "Orders routed to this facility from anywhere on the rail — your work queue.\n\n**Not implemented yet.** No /orders prefix exists under either version.\n\n**Keep from the response:** `orders[].order_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "performer_facility", "in": "query", "required": true, "description": "facility code", "schema": { "type": "string" }, "example": "" }, { "name": "status", "in": "query", "required": true, "description": "status", "schema": { "type": "string" }, "example": "routed" } ], "responses": { "200": { "description": "Returns `orders[].order_id`." } } } }, "/api/v1/orders/{order_id}/results": { "post": { "tags": [ "05 · Treat" ], "operationId": "orders.result", "summary": "Return the result against the order. It reaches the requester without a second integration.", "description": "Return the result against the order. It reaches the requester without a second integration.\n\n**Not implemented yet.** No /orders prefix exists under either version.\n\n**Keep from the response:** `result_ref`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "order_id", "in": "path", "required": true, "description": "order id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `result_ref`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "final" }, "observations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "object", "properties": { "system": { "type": "string", "example": "LOINC" }, "code": { "type": "string", "example": "718-7" } } }, "valueQuantity": { "type": "object", "properties": { "value": { "type": "number", "example": 9.1 }, "unit": { "type": "string", "example": "g/dL" } } }, "interpretation": { "type": "string", "example": "L" } } } }, "performed_by": { "type": "object", "properties": { "hwr_number": { "type": "string", "example": "{{hwr_number}}" } } } } }, "example": { "status": "final", "observations": [ { "code": { "system": "LOINC", "code": "718-7" }, "valueQuantity": { "value": 9.1, "unit": "g/dL" }, "interpretation": "L" } ], "performed_by": { "hwr_number": "{{hwr_number}}" } } } } } } }, "/api/v1/prescriptions": { "post": { "tags": [ "05 · Treat" ], "operationId": "prescriptions.create", "summary": "Prescribe. Routed to the pharmacy the patient chooses, which may not be yours.", "description": "Prescribe. Routed to the pharmacy the patient chooses, which may not be yours.\n\n**Keep from the response:** `prescription_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "responses": { "200": { "description": "Returns `prescription_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "medication": { "type": "object", "properties": { "system": { "type": "string", "example": "KEML" }, "code": { "type": "string", "example": "AL-20-120" }, "display": { "type": "string", "example": "Artemether/Lumefantrine 20/120mg" } } }, "dose": { "type": "string", "example": "4 tablets" }, "route": { "type": "string", "example": "oral" }, "frequency": { "type": "string", "example": "BD" }, "duration_days": { "type": "number", "example": 3 }, "quantity": { "type": "number", "example": 24 }, "substitution_allowed": { "type": "boolean", "example": true } } } }, "diagnosis": { "type": "array", "items": { "type": "object", "properties": { "icd11_code": { "type": "string", "example": "1F41" } } } }, "prescriber": { "type": "object", "properties": { "hwr_number": { "type": "string", "example": "{{hwr_number}}" } } }, "route_to_facility": { "type": "string", "example": "{{facility_code}}" } } }, "example": { "items": [ { "medication": { "system": "KEML", "code": "AL-20-120", "display": "Artemether/Lumefantrine 20/120mg" }, "dose": "4 tablets", "route": "oral", "frequency": "BD", "duration_days": 3, "quantity": 24, "substitution_allowed": true } ], "diagnosis": [ { "icd11_code": "1F41" } ], "prescriber": { "hwr_number": "{{hwr_number}}" }, "route_to_facility": "{{facility_code}}" } } } } }, "get": { "tags": [ "05 · Treat" ], "operationId": "prescriptions.inbox", "summary": "Prescriptions routed to this pharmacy, written anywhere. Nothing is carried in on paper.", "description": "Prescriptions routed to this pharmacy, written anywhere. Nothing is carried in on paper.\n\n**Keep from the response:** `prescriptions[].prescription_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "responses": { "200": { "description": "Returns `prescriptions[].prescription_id`." } } } }, "/api/v1/prescriptions/dispense": { "post": { "tags": [ "05 · Treat" ], "operationId": "prescriptions.dispense", "summary": "Record what was actually handed over, including a substitution or a partial fill.", "description": "Record what was actually handed over, including a substitution or a partial fill.\n\n**Keep from the response:** `dispense_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "responses": { "200": { "description": "Returns `dispense_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "medication": { "type": "object", "properties": { "system": { "type": "string", "example": "KEML" }, "code": { "type": "string", "example": "AL-20-120" } } }, "quantity_dispensed": { "type": "number", "example": 24 }, "substituted": { "type": "boolean", "example": false }, "batch": { "type": "string", "example": "AL-2411-08" } } } }, "dispensed_by": { "type": "object", "properties": { "hwr_number": { "type": "string", "example": "{{hwr_number}}" } } } } }, "example": { "items": [ { "medication": { "system": "KEML", "code": "AL-20-120" }, "quantity_dispensed": 24, "substituted": false, "batch": "AL-2411-08" } ], "dispensed_by": { "hwr_number": "{{hwr_number}}" } } } } } } }, "/api/v1/prescriptions/doctors": { "delete": { "tags": [ "05 · Treat" ], "operationId": "prescriptions.doctors.remove", "summary": "Remove a doctor from a prescription recorded against the wrong prescriber.", "description": "Remove a doctor from a prescription recorded against the wrong prescriber.\n\n**Keep from the response:** `status`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "responses": { "200": { "description": "Returns `status`." } } } }, "/api/v1/visits/{visit_id}/documents/generate": { "post": { "tags": [ "05 · Treat" ], "operationId": "documents.generate", "summary": "Generate the documents this claim requires from the clinical data already recorded.", "description": "Generate the documents this claim requires from the clinical data already recorded.\n\n**Not implemented yet.** No document routes under a visit. Rendering is live at a different address: POST /api/v1/clinical/document-bundles/{id}/pdf renders a bundle, and POST /api/v1/clinical/html-to-pdf converts HTML you supply. Neither generates a document set from a visit's clinical data.\n\n**Keep from the response:** `documents[].document_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `documents[].document_id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string", "example": "DOC-2026-08-14-007731" }, "document_type": { "type": "string", "example": "DISCHARGE_SUMMARY" }, "status": { "type": "string", "example": "generated" }, "attached_to_visit": { "type": "boolean", "example": true }, "missing": { "type": "array", "items": { "type": "object" } } } } } } }, "example": { "documents": [ { "document_id": "DOC-2026-08-14-007731", "document_type": "DISCHARGE_SUMMARY", "status": "generated", "attached_to_visit": true, "missing": [] }, { "document_id": null, "document_type": "CLAIM_FORM", "status": "incomplete", "missing": [ "encounter.period.end", "diagnosis.primary" ] } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document_types": { "type": "array", "items": { "type": "string", "example": "DISCHARGE_SUMMARY" } }, "format": { "type": "string", "example": "pdf" } } }, "example": { "document_types": [ "DISCHARGE_SUMMARY", "CLAIM_FORM" ], "format": "pdf" } } } } } }, "/api/v1/visits/{visit_id}/documents/{document_type}/render": { "get": { "tags": [ "05 · Treat" ], "operationId": "documents.render", "summary": "Render a document on demand — HTML to show on screen, PDF to hand over or sign.", "description": "Render a document on demand — HTML to show on screen, PDF to hand over or sign.\n\n**Not implemented yet.** No document routes under a visit. GET /api/v1/clinical/document-bundles/{id}/render is the live renderer, scoped to a bundle rather than to a visit and a document type.\n\n**Keep from the response:** `url`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" }, { "name": "document_type", "in": "path", "required": true, "description": "document type", "schema": { "type": "string" }, "example": "" }, { "name": "format", "in": "query", "required": true, "description": "format", "schema": { "type": "string" }, "example": "html" } ], "responses": { "200": { "description": "Returns `url`." } } } }, "/api/v1/visits/{visit_id}/referrals": { "post": { "tags": [ "05 · Treat" ], "operationId": "referrals.create", "summary": "Refer onward, carrying the clinical record and the authorisation taken here.", "description": "Refer onward, carrying the clinical record and the authorisation taken here.\n\n**Not implemented yet.** No /referrals prefix exists, and there is no referral surface in the service.\n\n**Keep from the response:** `referral_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `referral_id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "referral_id": { "type": "string", "example": "REF-2026-08-14-000904" }, "status": { "type": "string", "example": "sent" }, "to_facility": { "type": "string", "example": "FR-11009" }, "authorization": { "type": "object", "properties": { "authorization_ref": { "type": "string", "example": "AUTH-2026-08-14-4471" }, "authenticated_at_facility": { "type": "string", "example": "FR-14082" }, "honoured_at_destination": { "type": "boolean", "example": true }, "expires_at": { "type": "string", "example": "2026-08-21T23:59:59+03:00" } } } } }, "example": { "referral_id": "REF-2026-08-14-000904", "status": "sent", "to_facility": "FR-11009", "authorization": { "authorization_ref": "AUTH-2026-08-14-4471", "authenticated_at_facility": "FR-14082", "honoured_at_destination": true, "expires_at": "2026-08-21T23:59:59+03:00" } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_facility": { "type": "string", "example": "{{referral_facility}}" }, "reason": { "type": "array", "items": { "type": "object", "properties": { "icd11_code": { "type": "string", "example": "1F41" } } } }, "urgency": { "type": "string", "example": "routine" }, "requested_service": { "type": "object", "properties": { "system": { "type": "string", "example": "ICHI" }, "code": { "type": "string", "example": "QBA1" } } }, "include_clinical": { "type": "boolean", "example": true }, "authorization_ref": { "type": "string", "example": "{{authorization_ref}}" }, "specimen_accompanying": { "type": "boolean", "example": false } } }, "example": { "to_facility": "{{referral_facility}}", "reason": [ { "icd11_code": "1F41" } ], "urgency": "routine", "requested_service": { "system": "ICHI", "code": "QBA1" }, "include_clinical": true, "authorization_ref": "{{authorization_ref}}", "specimen_accompanying": false } } } } } }, "/api/v1/referrals": { "get": { "tags": [ "05 · Treat" ], "operationId": "referrals.inbox", "summary": "Referrals sent to this facility, with the record and the authorisation already attached.", "description": "Referrals sent to this facility, with the record and the authorisation already attached.\n\n**Not implemented yet.** No /referrals prefix exists.\n\n**Keep from the response:** `referrals[].referral_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "facility_code", "in": "query", "required": true, "description": "facility code", "schema": { "type": "string" }, "example": "" }, { "name": "direction", "in": "query", "required": true, "description": "direction", "schema": { "type": "string" }, "example": "inbound" } ], "responses": { "200": { "description": "Returns `referrals[].referral_id`." } } } }, "/api/v1/referrals/{referral_id}/accept": { "post": { "tags": [ "05 · Treat" ], "operationId": "referrals.accept", "summary": "Accept or decline a referral, and open the receiving visit against the same authorisation.", "description": "Accept or decline a referral, and open the receiving visit against the same authorisation.\n\n**Not implemented yet.** No /referrals prefix exists.\n\n**Keep from the response:** `visit_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "referral_id", "in": "path", "required": true, "description": "referral id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `visit_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "example": "accepted" }, "expected_at": { "type": "string", "example": "2026-08-15T08:00:00+03:00" }, "receiving_clinician": { "type": "object", "properties": { "hwr_number": { "type": "string", "example": "{{hwr_number}}" } } } } }, "example": { "decision": "accepted", "expected_at": "2026-08-15T08:00:00+03:00", "receiving_clinician": { "hwr_number": "{{hwr_number}}" } } } } } } }, "/api/v1/referrals/{referral_id}/samples": { "post": { "tags": [ "05 · Treat" ], "operationId": "samples.send", "summary": "Send a specimen to the hub, tracked against the order that asked for it.", "description": "Send a specimen to the hub, tracked against the order that asked for it.\n\n**Not implemented yet.** Hangs off the unregistered /referrals prefix.\n\n**Keep from the response:** `sample_id`\n\n**Taught in:** [05 · Treat](/rail/stops/Treat)", "parameters": [ { "name": "referral_id", "in": "path", "required": true, "description": "referral id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `sample_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "string", "example": "{{order_id}}" }, "specimen": { "type": "object", "properties": { "type": { "type": "string", "example": "BLD" }, "container": { "type": "string", "example": "EDTA" }, "collected_at": { "type": "string", "example": "2026-08-14T09:12:00+03:00" } } }, "cold_chain": { "type": "boolean", "example": true }, "courier_ref": { "type": "string", "example": "CR-88213" } } }, "example": { "order_id": "{{order_id}}", "specimen": { "type": "BLD", "container": "EDTA", "collected_at": "2026-08-14T09:12:00+03:00" }, "cold_chain": true, "courier_ref": "CR-88213" } } } } } }, "/api/v1/preauths": { "post": { "tags": [ "06 · Preauthorize" ], "operationId": "preauth.submit", "summary": "Submit a preauthorisation for approval.", "description": "Submit a preauthorisation for approval.\n\n**Keep from the response:** `reference`\n\n**Taught in:** [06 · Preauthorize](/rail/stops/Preauth)", "responses": { "200": { "description": "Returns `reference`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visit_id": { "type": "string", "example": "{{visit_id}}" }, "request_type": { "type": "string", "example": "planned" }, "narrative": { "type": "string", "example": "Recurrent gross haematuria under investigation; contrast CT abdomen indicated to exclude renal mass." }, "service_start": { "type": "string", "example": "2026-08-10" }, "frequency": { "type": "string", "example": "once" }, "items": { "type": "array", "items": { "type": "object", "properties": { "billing_code": { "type": "string", "example": "{{billing_code}}" }, "quantity": { "type": "number", "example": 1 } } } }, "diagnosis": { "type": "object", "properties": { "icd11_code": { "type": "string", "example": "GB70.1" }, "description": { "type": "string", "example": "Haematuria, unspecified" } } }, "doctor": { "type": "object", "properties": { "hwr_number": { "type": "string", "example": "{{hwr_number}}" }, "name": { "type": "string", "example": "Dr. Faith Wanjiru" } } } } }, "example": { "visit_id": "{{visit_id}}", "request_type": "planned", "narrative": "Recurrent gross haematuria under investigation; contrast CT abdomen indicated to exclude renal mass.", "service_start": "2026-08-10", "frequency": "once", "items": [ { "billing_code": "{{billing_code}}", "quantity": 1 } ], "diagnosis": { "icd11_code": "GB70.1", "description": "Haematuria, unspecified" }, "doctor": { "hwr_number": "{{hwr_number}}", "name": "Dr. Faith Wanjiru" } } } } } }, "get": { "tags": [ "06 · Preauthorize" ], "operationId": "preauth.poll", "summary": "Poll for the decision. Identical body to the callback.", "description": "Poll for the decision. Identical body to the callback.\n\n**Keep from the response:** `authorization_code`\n\n**Taught in:** [06 · Preauthorize](/rail/stops/Preauth)", "parameters": [ { "name": "preauth_reference", "in": "query", "required": true, "description": "preauth reference", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `authorization_code`." } } } }, "/api/v2/visits/{visit_ref}/bill-lines": { "post": { "tags": [ "07 · Bill" ], "operationId": "billline.add", "summary": "Charge under an authorized service line — payer-first. The payer answers with the covered amount and the patient's copay; a line with no service_line_ref is self pay.", "description": "Charge under an authorized service line — payer-first. The payer answers with the covered amount and the patient's copay; a line with no service_line_ref is self pay.\n\n**Keep from the response:** `bill_line_ref`\n\n**Taught in:** [07 · Bill](/rail/stops/Bill)", "parameters": [ { "name": "visit_ref", "in": "path", "required": true, "description": "visit ref", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `bill_line_ref`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "{{intervention_code}}" }, "name": { "type": "string", "example": "Consultation, outpatient" }, "quantity": { "type": "string", "example": "1" }, "amount": { "type": "string", "example": "1500.00" }, "service_line_ref": { "type": "string", "example": "{{service_line_ref}}" }, "practitioner_ref": { "type": "string", "example": "{{practitioner_ref}}" } } }, "example": { "code": "{{intervention_code}}", "name": "Consultation, outpatient", "quantity": "1", "amount": "1500.00", "service_line_ref": "{{service_line_ref}}", "practitioner_ref": "{{practitioner_ref}}" } } } } } }, "/api/v1/visits/{visit_id}/documents": { "post": { "tags": [ "07 · Bill" ], "operationId": "documents.attach", "summary": "Attach a required document against the visit.", "description": "Attach a required document against the visit.\n\n**Not implemented yet.** No route attaches a document to a visit. GET /api/v2/visits/{visit_ref}/documents lists what is attached, and POST /api/v1/clinical/documents/import brings a clinical document in.\n\n**Keep from the response:** `document_id`\n\n**Taught in:** [07 · Bill](/rail/stops/Bill)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `document_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "example": "final_bill" }, "document_type": { "type": "string", "example": "FINAL_BILL" }, "file_ref": { "type": "string", "example": "{{file_ref}}" } } }, "example": { "key": "final_bill", "document_type": "FINAL_BILL", "file_ref": "{{file_ref}}" } } } } } }, "/api/v1/visits/{visit_id}/level-changes": { "post": { "tags": [ "07 · Bill" ], "operationId": "level.change", "summary": "Retire a per-diem line and start a new one at a different level.", "description": "Retire a per-diem line and start a new one at a different level.\n\n**Not implemented yet.** No /level-changes route is registered.\n\n**Keep from the response:** `new_line_id`\n\n**Taught in:** [07 · Bill](/rail/stops/Bill)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `new_line_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_billing_code": { "type": "string", "example": "TBC-WARD-NORM" }, "to_billing_code": { "type": "string", "example": "TBC-WARD-ICU" }, "effective_at": { "type": "string", "example": "2026-08-07T06:00:00+03:00" }, "reason": { "type": "string", "example": "Deteriorating respiratory status; ICU admission." } } }, "example": { "from_billing_code": "TBC-WARD-NORM", "to_billing_code": "TBC-WARD-ICU", "effective_at": "2026-08-07T06:00:00+03:00", "reason": "Deteriorating respiratory status; ICU admission." } } } } } }, "/api/v1/visits/{visit_id}/claim/preflight": { "post": { "tags": [ "08 · Submit" ], "operationId": "claim.preflight", "summary": "Run every gate and return all failures at once.", "description": "Run every gate and return all failures at once.\n\n**Not implemented yet.** Not registered on this path. The registered preflight is POST /api/v2/visits/{visit_ref}/preauths/preflight, which is a preauth check rather than a claim one.\n\n**Keep from the response:** `reasons[]`\n\n**Taught in:** [08 · Submit](/rail/stops/Submit)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `reasons[]`." } } } }, "/api/v1/visits/{visit_id}/claim/close": { "post": { "tags": [ "08 · Submit" ], "operationId": "claim.close", "summary": "Close the visit and submit. Idempotent on external_id.", "description": "Close the visit and submit. Idempotent on external_id.\n\n**Not implemented yet.** Not registered on this path. The nearest registered routes are POST /api/v1/claims/close and POST /api/v1/visits/{visit_id}/close.\n\n**Keep from the response:** `claim_id`\n\n**Taught in:** [08 · Submit](/rail/stops/Submit)", "parameters": [ { "name": "visit_id", "in": "path", "required": true, "description": "visit id", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `claim_id`." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string", "example": "{{external_id}}" }, "discharge_reason": { "type": "string", "example": "RECOVERED" }, "closing_authorization_ref": { "type": "string", "example": "{{closing_authorization_ref}}" } } }, "example": { "external_id": "{{external_id}}", "discharge_reason": "RECOVERED", "closing_authorization_ref": "{{closing_authorization_ref}}" } } } } } }, "/api/v1/remittances": { "get": { "tags": [ "09 · Reconcile" ], "operationId": "remittances.poll", "summary": "Paginated remittances since a timestamp.", "description": "Paginated remittances since a timestamp.\n\n**Not implemented yet.** No /remittances route is registered.\n\n**Keep from the response:** `remittance_id`\n\n**Taught in:** [09 · Reconcile](/rail/stops/Reconcile)", "parameters": [ { "name": "since", "in": "query", "required": true, "description": "since", "schema": { "type": "string" }, "example": "" } ], "responses": { "200": { "description": "Returns `remittance_id`." } } } } } }