# Slade360° Advantage API Documentation

> Full documentation content, for language models.

---

## /docs/eTIMS/Getting-Started

# Getting Started

# Getting started with Slade360 eTIMS APIs

The Slade360 eTIMS API connects your systems to the Kenya Revenue Authority's (KRA) Electronic Tax Invoice Management System (eTIMS). These pages are written for the developers doing the integration and for the businesses that have to file through it.

## Overview

The API handles the tax compliance work, which breaks down into five areas:

- Authentication: OAuth 2.0 secures access to the API.
- Branch management: register branches and keep them up to date if you run more than one.
- Device management: initialize ETRs and other fiscal devices, and manage them afterwards.
- Invoicing: create, validate, and send tax invoices as the sales happen.
- Customer and supplier management: keep your records of business partners correct.

## Next steps

Take them in this order:

1. [Self onboard on eTIMS](/docs/eTIMS/How-To-Guides/Self-Onboard-on-eTIMS): create the account and activate the business. Nothing below answers until this is done.
2. [Start using the eTIMS API](/docs/eTIMS/How-To-Guides/Start-Using-the-eTIMS-API): get credentials, get an access token, and see how VSCU deployment is handled.
3. [Branches](/etims-api/branches): register a branch and keep it in step with eTIMS, so transactions are tracked against the right one.
4. [Create an eTIMS invoice](/docs/eTIMS/How-To-Guides/Create-an-eTIMS-Invoice): draft, add lines, process, sign.

The sidebar has the detailed guides, and [the full API reference](/etims-api) covers every module.

---

## /docs/eTIMS/How-To-Guides/Create-an-eTIMS-Invoice

# Create an eTIMS Invoice

This guide covers issuing a compliant tax invoice, starting from a draft and
ending with a signed invoice that carries the KRA verification details (CU
invoice number and QR code).

> **Prerequisites**
> - You've [onboarded and activated your business](/docs/eTIMS/How-To-Guides/Self-Onboard-on-eTIMS).
> - You have an access token. See [Authentication API](/auth-api). Send it as `Authorization: Bearer <access_token>` on every request.
> - Your branch device is active and your items and customer exist.

## Step 1: Create the invoice (draft)

Create the invoice header with the customer and branch details.

`POST /api/sales/salesinvoices`. See [Add Sale](/etims-api) in the API
reference. Save the `id` it returns; you'll use it as `invoice_id` in the next
steps.

## Step 2: Add invoice lines

Add one line per product or service sold, each with quantity, unit price, and
tax rate (KRA tax categories A to E).

`POST /api/sales/salesinvoicelines`. Reference the `invoice_id` from Step 1.

## Step 3: Process the invoice

Move the invoice through its workflow (Draft → Submit → Approve):

`POST /api/sales/salesinvoices/{invoice_id}/transition/DRAFT_SUBMIT_APPROVE`

## Step 4: Sign the invoice

Signing sends the invoice to KRA through the device and returns the fiscal
details:

`POST /api/sales/salesinvoices/{invoice_id}/sign_sales_invoice`

A signed invoice includes the CU invoice number, the KRA verification code, and
a QR code the customer can scan to check that the invoice is genuine.

## Step 5: Retrieve or download the signed invoice

`GET /api/sales/salesinvoices/{invoice_id}/download`

## Try it interactively

Open the [eTIMS API Reference](/etims-api), set your token with the
**Set API Token** button in the top bar, and run each call above with **Try it**.

## Related

- Credit notes follow the same flow: create, process, then sign the credit note.
- [Start Using the Slade360 eTIMS API](/docs/eTIMS/How-To-Guides/Start-Using-the-eTIMS-API) covers the full integration and go-live path.

---

## /docs/eTIMS/How-To-Guides/Querying-List-Endpoints

# Querying List Endpoints

Every eTIMS list endpoint (`GET` collections such as
`/api/etims/item_classifications/`) takes the same set of query parameters, so
you can pick out the fields you need, filter, search, and paginate. Use them
rather than pulling a whole collection and trimming it on the client.

The examples below use the item classifications list, but the parameters are the
same on every list endpoint.

> **Base URLs.** Development `https://api-dev.slade360edi.com/erp`,
> Production `https://api.erp.slade360.co.ke`. All examples require
> `Authorization: Bearer <access_token>` (see
> [Start Using the eTIMS API](/docs/eTIMS/How-To-Guides/Start-Using-the-eTIMS-API)).

## Field selection (sparse fieldsets)

Pass a comma-separated `fields` parameter and each result comes back with only
those fields. Payloads shrink and responses get faster.

```bash
curl --request GET \
  --url 'https://api-dev.slade360edi.com/erp/api/etims/item_classifications/?fields=classification_code,classification_name' \
  --header 'Authorization: Bearer <access_token>'
```

Each result then contains only the requested fields:

```json
{
  "count": 1240,
  "next": "...?page=2",
  "previous": null,
  "page_size": 15,
  "current_page": 1,
  "total_pages": 83,
  "start_index": 1,
  "end_index": 15,
  "results": [
    { "classification_code": "50131600", "classification_name": "Eggs and egg substitutes" }
  ]
}
```

Notes:

- `fields` is honoured on `GET` requests only. It has no effect on writes.
- List the top-level field names, comma-separated. Spaces are not required.
- An unknown field name is rejected with `400 Bad Request`, and the error lists
  the fields you can use, so a typo shows up straight away instead of being
  quietly dropped:

  ```json
  {
    "fields": "Unknown field(s): ['classificaton_name']. Allowed fields: ['active', 'classification_code', 'classification_name', 'created', 'id', ...]."
  }
  ```

- Omit `fields` to get the full representation.

## Filtering

Filter on any model field with `?<field>=<value>`. Text fields such as
`classification_name` match on partial values and ignore case (`contains`); most
other fields need an exact match.

```bash
# Exact match on the KRA classification code
curl --url '.../api/etims/item_classifications/?classification_code=50131600' ...

# Partial, case-insensitive match on the name
curl --url '.../api/etims/item_classifications/?classification_name=egg' ...
```

## Search

Use `?search=` to match a term across the endpoint's searchable fields. For item
classifications those are `classification_name` and `classification_code`, and a
single term matches either:

```bash
curl --url '.../api/etims/item_classifications/?search=egg' ...
```

## Pagination

List responses are paginated and wrapped in an envelope with `count`, `next`,
`previous`, `page_size`, `current_page`, `total_pages`, `start_index`,
`end_index`, and `results`.

| Parameter | Default | Notes |
|-----------|---------|-------|
| `page` | `1` | Page number to fetch. |
| `page_size` | `15` | Results per page. Capped at 50: larger values are clamped down to 50 rather than honoured. |

```bash
curl --url '.../api/etims/item_classifications/?page=2&page_size=50' ...
```

> **Why `page_size` looks broken.** Values above 50 are clamped to 50 without an
> error, so a single page will never hold more than 50 records. If you are after
> one specific record, filter or search for it (above) rather than paging through
> the whole collection. To pull an entire collection, page through it with
> `?page=N&page_size=50` until `next` is `null`.

## Combining parameters

The parameters compose. This fetches page 1 of the egg-related classifications,
50 at a time, with only the code and name in each result:

```bash
curl --request GET \
  --url 'https://api-dev.slade360edi.com/erp/api/etims/item_classifications/?search=egg&fields=classification_code,classification_name&page=1&page_size=50' \
  --header 'Authorization: Bearer <access_token>'
```

## Related

- [Item Classification (KRA)](/docs/eTIMS/References/Item/Item-Classification) lists the classification codes and the hierarchy.
- [eTIMS API Reference](/etims-api) has all the endpoints, each with an interactive "Try it".

---

## /docs/eTIMS/How-To-Guides/Self-Onboard-on-eTIMS

# Self Onboard on eTIMS

You can create a Slade360 Advantage account and activate your business for
eTIMS yourself. Nobody has to provision it for you, and the wizard walks you
through each screen. Budget a few minutes.

## Step 1: Open the onboarding page

Go to **[dev.advantage.slade360.com/auth/welcome](https://dev.advantage.slade360.com/auth/welcome)**
and click **Get Started**.

If you already have an account, choose **Sign In** instead.

![Slade360 Advantage welcome page with Sign In and Get Started buttons](/onboarding/01-welcome.png)

## Step 2: Select your account type

Choose how you're setting up:

| Account type | Use it for |
|--------------|------------|
| **Business** *(recommended)* | Clinics, facilities, or businesses operating one or more locations. |
| **Individual** | Solo practitioners and independent health or wellness professionals. |

Most eTIMS users want Business. You can change it later.

![Select account type screen showing Individual and Business options](/onboarding/02-select-account-type.png)

## Step 3: Verify Admin ID

Step 1 of 3 in the setup wizard. Enter the administrator's professional
details, then confirm the emailed link and type in the SMS code to prove the
admin is who they say they are.

![Step 1 of 3, Verify Admin ID, entering professional details](/onboarding/03-verify-admin-id.png)

> If a connected registry already holds your professional details, the form
> fills them in for you. If not, type them in yourself.

## Step 4: Setup Business

Step 2 of 3. Fill in your business name, KRA PIN, and the branch or branches
you operate. This is the organisation your eTIMS transactions get reported
under.

![Step 2 of 3, Setup Business](/onboarding/04-setup-business.png)

## Step 5: Activate Business

Step 3 of 3. Check your details and activate. When activation finishes, your
business is registered and can transact on eTIMS.

![Step 3 of 3, Activate Business](/onboarding/05-activate-business.png)

## What's next

- [Create an eTIMS Invoice](/docs/eTIMS/How-To-Guides/Create-an-eTIMS-Invoice) to issue your first signed tax invoice.
- [Start Using the Slade360 eTIMS API](/docs/eTIMS/How-To-Guides/Start-Using-the-eTIMS-API) to integrate programmatically and go live.

---

## /docs/eTIMS/How-To-Guides/Start-Using-the-eTIMS-API

# Start Using the Slade360 eTIMS API

This page covers the whole integration. You get credentials, build against the
development environment, then go live, with the VSCU deployment automated by
Slade360.

## 1. Get your credentials

[Onboard and activate your business](/docs/eTIMS/How-To-Guides/Self-Onboard-on-eTIMS),
then get a `client_id` and `client_secret` for your integration. Credentials are
issued per environment, so development and production have their own pair.

## 2. Authenticate

Exchange your credentials for an access token through the
[Authentication API](/auth-api), using the OAuth 2.0 client credentials grant:

```bash
curl --request POST \
  --url 'https://identity-dev.slade360edi.com/realms/slade360/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=<your_client_id>' \
  --data-urlencode 'client_secret=<your_client_secret>' \
  --data-urlencode 'grant_type=client_credentials'
```

Send the returned `access_token` as `Authorization: Bearer <access_token>` on
every API call. A token lasts 30 minutes, so request a new one once it expires.

## 3. Know your environments

| Environment | Authentication host | eTIMS API base URL |
|-------------|--------------------|--------------------|
| **Development** | `https://identity-dev.slade360edi.com` | `https://api-dev.slade360edi.com/erp` |
| **Production** | `https://identity.slade360edi.com` | `https://api.erp.slade360.co.ke` |

Build and test against development first.

## 4. Set up your data

Before you transact, make sure these exist. The
[eTIMS API Reference](/etims-api) has the endpoints for each.

1. Branches, one for every location you operate from.
2. Items and products, mapped to KRA item classifications.
3. Customers and suppliers, the business partners you trade with.
4. eTIMS codes and tax codes, synced so classification and tax come out right.

## 5. Test the whole flow

Run a full transaction in development.
[Create and sign an invoice](/docs/eTIMS/How-To-Guides/Create-an-eTIMS-Invoice),
check that it comes back with a CU invoice number and a QR code, then confirm it
shows up in eTIMS.

## 6. Go live

Once your integration passes in development:

1. Switch to the production credentials and base URLs in the table above.
2. Deploy the VSCU. The Virtual Secure Computing Unit (VSCU) is the secure
   component that signs transactions and sends them to KRA. Slade360 automates
   the deployment, so you don't provision it by hand. One is set up per branch
   as part of going live.
3. Initialize each branch device so it can transact. You do this once per
   branch.
4. Run a smoke test in production: issue one live invoice and confirm it signs.

> **Note:** You work through the exact go-live steps and the automated VSCU
> deployment with the Slade360 team during onboarding. Confirm the production
> checklist with your integration contact before you issue live invoices.

## Related

- [Authentication API](/auth-api): the reference for generating tokens.
- [eTIMS API Reference](/etims-api): every endpoint, each with a "Try it" button.

---

## /docs/eTIMS/Plugins/CargoWise/Invoice-Intake

# CargoWise Invoice Intake

# CargoWise plugin: invoice intake

The invoice intake endpoint takes invoice documents out of a CargoWise logistics system and runs them through the eTIMS pipeline. The platform converts them to the VSCU format KRA requires, sends them for validation, and returns a stamped document to the system that sent them.

### What is CargoWise?

CargoWise is a global logistics execution platform used for freight forwarding, customs brokerage, and supply chain management. For each invoice transaction it produces two independent XML documents:

| Document | Role |
|----------|------|
| XUT | Invoice trigger, holding the shipment and invoice data (transaction XML) |
| XUD | Invoice document, the document XML that accompanies the transaction |

CargoWise transmits the two files separately and independently, and either one can arrive before the other. The intake API sorts out the ordering for you.

---

## Overview

A CargoWise invoice submission runs like this:

1. CargoWise exports the XUT, the XUD, or both, for an invoice transaction.
2. Each document goes to the intake API as soon as it is available.
3. The platform checks the request (OAuth 2.0), stores the document, and holds it until the other half arrives.
4. Once both documents are in and paired, the job moves to `READY` and processing starts.
5. The platform converts the XUT data into VSCU format, the tax data structure KRA works with.
6. It sends the converted data to KRA for validation and signing.
7. KRA returns a signed response. The platform stamps the invoice and builds the final XUD output.
8. The stamped XUD goes back to the system that sent the documents.

---

## Document sequencing

The XUT and the XUD are separate files that CargoWise sends independently, so either one can turn up first. What the API does next depends on which one it already has:

| Scenario | Behaviour | Job Status |
|----------|-----------|------------|
| XUT arrives, XUD not yet received | Stored, waiting for its pair | `WAITING_FOR_XUD` |
| XUD arrives, XUT not yet received | Stored, waiting for its pair | `WAITING_FOR_XUT` |
| Second document arrives | Documents paired, processing starts | `READY` |
| Both submitted in a single request | Paired straight away, processing starts | `READY` |

> **Important:** out of order arrival is normal, but a document whose pair never follows at all is not. If a job sits in `WAITING_FOR_XUT` or `WAITING_FOR_XUD` for a long stretch, raise it with the team running the sending system.

>
> **Duplicate XUT submissions**
>
> CargoWise sometimes sends the same XUT more than once. The platform checks the invoice number on every submission so the same invoice is not processed twice. Give each transaction one invoice number and keep it the same on any resend.

---

## Invoice intake endpoint

### Endpoint details

| Property | Value |
|----------|-------|
| Method | `POST` |
| URL | `{{base_url}}/api/invoice/intake/` |
| Base URL | `https://adapters.erp.release.slade360edi.com` |
| Content-Type | `multipart/form-data` |
| Authentication | Bearer Token (OAuth 2.0) |

---

### Headers

| Header | Value | Required | Description |
|--------|-------|----------|-------------|
| `Authorization` | `Bearer <access_token>` | Yes | OAuth 2.0 Bearer token |
| `Idempotency-Key` | `{{$guid}}` | Recommended | A fresh UUID per request, so a retry is not processed twice |

>
> **Idempotency keys**
>
> Send a fresh `Idempotency-Key` (a UUID v4 works) with every intake request. If a retry carries the same key, the server replays the original response instead of processing the document again. A dropped connection or a timeout then cannot turn into a second submission.

---

### Request body

Send the body as `multipart/form-data` with these fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `xut` | File | Conditional | The XUT invoice trigger XML from CargoWise (shipment and invoice data) |
| `xud` | File | Conditional | The XUD invoice document XML from CargoWise |
| `source` | Text | Yes | Identifier for the originating system (e.g., `CARGOWISE`, `POSTMAN_TEST`) |

> **Note:** send at least one of `xut` or `xud`. Both can go in the same request, or each can go on its own as it becomes available.

#### Example file naming

CargoWise-generated files follow the pattern:

```
UDM_TRX_XDC_<sequence_number>_<document_identifier>
```

For example:
- `UDM_TRX_XDC_000000000001343490_0000000000001...` (XUT file)
- `UDM_TRX_XDC_000000000001111911_0000000000001...` (XUD file)

#### Example request with both documents

```bash
curl --request POST \
  --url https://adapters.erp.release.slade360edi.com/api/invoice/intake/ \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --form 'xut=@/path/to/UDM_TRX_XDC_0000000000015826490.xml' \
  --form 'xud=@/path/to/UDM_TRX_XDC_0000000000015826491.xml' \
  --form 'source=CARGOWISE'
```

#### Example request with the XUT only, XUD to follow

```bash
curl --request POST \
  --url https://adapters.erp.release.slade360edi.com/api/invoice/intake/ \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001' \
  --form 'xut=@/path/to/UDM_TRX_XDC_0000000000015826490.xml' \
  --form 'source=CARGOWISE'
```

---

### Responses

#### 202 Accepted (document received)

The API answers `202 Accepted` as soon as it has stored a document. Read the `status` field to see whether both documents are paired or the job is still waiting for its counterpart:

```json
{
    "job_id": "31fdf049-1b29-40fa-be16-9dc5eb164d66",
    "correlation_id": "sha256:e6d792462237ec5f7d03e96b9b039b512546efdb95bb98d744007696014b5c5d",
    "status": "READY"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `job_id` | UUID | Unique identifier for this document pair's processing job. Use it to track progress. |
| `correlation_id` | String | SHA-256 hash for tracing the request through the system. Include it when you contact support. |
| `status` | String | Current state of the job. The status values are listed below. |

#### Job status values

| Status | Meaning |
|--------|---------|
| `WAITING_FOR_XUD` | XUT received and stored, waiting for the XUD document to arrive. |
| `WAITING_FOR_XUT` | XUD received and stored, waiting for the XUT document to arrive. |
| `READY` | Both documents received and paired, processing has started. |

>
> **Asynchronous processing**
>
> `202 Accepted` means the document arrived, not that the work is finished. A status of `READY` means both documents are paired and the pipeline has started. Use the `job_id` to follow progress until KRA submission is confirmed.

---

#### 400 Bad Request (missing document)

If neither `xut` nor `xud` is provided, the API returns:

```json
{
    "non_field_errors": [
        "Provide at least one of xut or xud."
    ]
}
```

**Resolution:** include at least one of `xut` or `xud` in the request.

---

#### Common error codes

| Status Code | Error | Resolution |
|-------------|-------|------------|
| `400` | `Provide at least one of xut or xud.` | Include at least one file (`xut` or `xud`) in the request. |
| `401` | Unauthorized | The Bearer token is invalid or has expired. Get a new one. |
| `409` | Conflict (duplicate Idempotency-Key) | The key was already used, so the original response comes back. |
| `422` | Unprocessable Entity | The file is malformed, or it does not match the expected XUT or XUD schema. |
| `500` | Internal Server Error | Contact Slade360 support with your `correlation_id`. |

---

---

## /docs/eTIMS/Plugins/ERPNext/Getting-Started

# ERPNext plugin: Kenya Compliance via Slade 360

[Kenya Compliance via Slade 360](https://github.com/navariltd/kenya-compliance-via-slade) is a [Frappe/ERPNext](https://frappeframework.com/) app that connects your ERPNext instance to the Kenya Revenue Authority (KRA) eTIMS platform. It goes through the Slade 360 Advantage middleware and the Virtual Sales Control Unit (VSCU).

Once it is installed and configured, your team keeps working in ERPNext as usual and the app sends the transactions on to KRA.

| Item | Value |
|------|-------|
| Source repository | [github.com/navariltd/kenya-compliance-via-slade](https://github.com/navariltd/kenya-compliance-via-slade) |
| App name (bench) | `kenya_compliance_via_slade` |
| Full guide (wiki) | [Complete Guide](https://github.com/navariltd/kenya-compliance-via-slade/wiki) |
| Compliance pathway | ERPNext → Slade 360 Advantage → KRA eTIMS |

---

## How it works

The app runs inside ERPNext and talks to the eTIMS servers. Data moves in one direction:

```
ERPNext  →  Kenya Compliance app  →  Slade 360 Advantage  →  KRA eTIMS
```

- You create business documents (invoices, items, customers, stock movements) in ERPNext as normal.
- When a document is finalised, or on a schedule if you have set one, the app converts it to the VSCU format KRA expects and submits it.
- KRA validates and signs the transaction. The app writes the returned SCU data back onto the ERPNext document, including the QR code on sales invoices.
- Every request is logged in the Integration Request DocType, and failures land in the Error Log DocType, which is where you look when something breaks.

### What it handles

| Area | What is synced |
|------|----------------|
| Sales invoices | Signed tax invoices + credit notes, with SCU data and QR codes |
| Purchase invoices | Purchase submission and registered-purchase fetch from eTIMS |
| Items | Item registration with KRA classification codes; opening stock balances |
| Customers & Suppliers | Registration and updates, individually, in bulk, or automatically |
| Stock | Stock Ledger Entries submitted via background jobs for real-time inventory |
| BOMs | Bill of Materials submission |
| Imports | Fetch and map imported-goods data from eTIMS |

> Note: registration with KRA and VSCU provisioning both go through an approved third party. Get your credentials from [etims@savannahinformatics.com](mailto:etims@savannahinformatics.com) before you configure the app.

---

## Prerequisites

Before installing, make sure you have:

- A running ERPNext site (v14+) on a working [Frappe Bench](https://frappeframework.com/docs/user/en/installation), or a Frappe Cloud bench.
- Administrator access to that site.
- Your eTIMS and Slade 360 credentials, meaning Client Key, Client Secret, username, password, Branch ID, and Device Serial Number. These are issued during VSCU registration ([etims@savannahinformatics.com](mailto:etims@savannahinformatics.com)).
- A Company already created in ERPNext with the correct KRA PIN.

---

## Installation

Choose the path that matches your hosting setup.

### Option A: self-hosted (Frappe Bench)

Run these commands in an active Bench terminal, from your `frappe-bench` directory.

First, download the app into the bench:

```sh
bench get-app https://github.com/navariltd/kenya-compliance-via-slade.git
```

Then install it onto your site:

```sh
bench --site <your.site.name.here> install-app kenya_compliance_via_slade
```

Finally, run the migrations and restart:

```sh
bench --site <your.site.name.here> migrate
bench restart
```

> Replace `<your.site.name.here>` with your actual site name (e.g. `erp.mycompany.co.ke`).

To pull a specific branch or version, append `--branch <branch-name>` to the `get-app` command.

### Option B: Frappe Cloud

On [Frappe Cloud](https://frappecloud.com/docs/introduction) you do not run bench commands yourself. You add the app from the dashboard.

1. Open your Bench in the Frappe Cloud dashboard and go to the Apps tab.
2. Click Add App.
3. If the app appears in the marketplace search, select it. Otherwise choose Install from GitHub and point it at the repository:
   `https://github.com/navariltd/kenya-compliance-via-slade`
4. Add the app to the bench, wait for the build to finish, then install it on your site from the site's Apps tab.
5. Frappe Cloud runs the migration automatically after installation.

---

## Verifying the installation

After the install, check that the app is on the site:

```sh
bench --site <your.site.name.here> list-apps
```

`kenya_compliance_via_slade` should appear in the list. In the ERPNext desk you will also see a new eTims workspace with shortcuts to the DocTypes you need.

---

## Post-install setup and configuration

Configure the app from inside ERPNext. Everything lives in the eTims Settings (Environment Settings) DocType.

1. Create the eTims Settings record. Open eTims Settings → New, and fill in:

   - Branch ID and Device Serial Number, from your KRA VSCU registration.
   - Company, the ERPNext company this branch reports under.
   - Server URL and Auth Server URL, the eTIMS endpoints for your environment.
   - Client Secret, Client Key, Username and Password, from Slade 360 (Authentication Details tab).
   - The Sandbox checkbox: tick it for testing, untick it for production.
   - Is Active, to mark the record active. Only one active record is allowed per environment + company + branch combination.

2. Fetch all codes. Click Get Codes to pull the latest classification, tax, and reference codes from the eTIMS servers.

3. Sync organisation structures. Click Sync Organisation Units to synchronise your branches, company, departments, and workstations with the Slade server.

4. Submit modes of payment. Click Submit Mode of Payments to register your payment methods.

5. Submit customers and suppliers. From the Customer and Supplier list views, use Submit Customers and Submit Suppliers to register your business partners, one at a time or in bulk.

6. Classify and register items. From the Item list view, classify each item against the KRA codes and submit it to eTIMS. Items can also go automatically on create or update, once you enable that setting.

The same settings document controls how often submissions run, and whether sales, purchases, and stock go automatically.

---

## Testing (self-hosted)

Turn testing on for the site, then run the suite:

```sh
bench --site <your.site.name.here> set-config allow_tests true
bench --site <your.site.name.here> run-tests --app kenya_compliance_via_slade
```

---

## Troubleshooting

- If requests are not reaching KRA, check the Integration Request DocType for the outbound payload and the response, and the Error Log DocType for exceptions.
- If a token has expired, you do not need to do anything. The access token regenerates on the next eTIMS request.
- If background jobs are not running, check that the bench workers and the scheduler are up (`bench doctor`, `bench enable-scheduler`).

---

## Support

- For registration and VSCU setup, email [etims@savannahinformatics.com](mailto:etims@savannahinformatics.com).

---

## /docs/eTIMS/References/Customers/Taxpayer-Status

# Taxpayer Status

The **taxpayer status code** (`taxprSttsCd`) tells you whether a taxpayer,
the customer, is active.

| Code | Name | Description |
|------|------|-------------|
| **A** | Active | Active. |
| **D** | Inactive | Inactive. |

*Source: KRA OSCU Specification v2.1 §4.2 (Code Classification 15, Taxpayer Status).*

---

## /docs/eTIMS/References/Imports/Import-Item-Status

# Import Item Status

The **import item status code** (`imptItemSttsCd`) says how far an imported item
has got on its way from the customs declaration into your inventory.

| Code | Status |
|------|--------|
| **1** | Unsent |
| **2** | Waiting |
| **3** | Approved |
| **4** | Cancelled |

*Source: KRA OSCU Specification v2.1 §4.16 (Code Classification 26, Import Item Status).*

---

## /docs/eTIMS/References/Item/Item-Classification

# List KRA Item Classification

KRA Item Classification is how the Kenya Revenue Authority (KRA) groups items by their tax treatment.

The classification you give an item is what sets the tax rate it attracts, whether it is exempt, and what you have to report for it, and this differs across goods and services.

> ### Why item classifications?
>
> Listing KRA item classifications from the Slade360 eTIMS APIs is how a business keeps its tax filings compliant and its records accurate.

### Classification levels

The classification hierarchy uses four levels:

| Level | Description |
|-------|-------------|
| 1 | Top-level category (e.g., VAT Act) |
| 2 | Major grouping (e.g., Goods, Services) |
| 3 | Sub-category (e.g., Exempt Goods, Zero Rated Goods) |
| 4 | Specific item or tariff-level entry |

### Item classification codes

| itemClsCd | itemClsNm | itemClsLvl |
|-----------|-----------|------------|
| 99000000 | VAT Act | 1 |
| 99010000 | Goods | 2 |
| 99011000 | Exempt Goods (Paragraph 1 - 99) | 3 |
| 99011001 | Bovine Semen of tariff number 05111000 | 4 |
| 99011002 | Fish eggs and roes of tariff number 0511990110 | 4 |
| 99011003 | Animal semen other than of bovine of tariff number 0511999010 | 4 |
| 99011004 | Soya beans whether or not broken of tariff numbers 12011000 and 12019000 | 4 |
| 99011005 | Groundnuts not roasted or otherwise cooked In shell of tariff number 12024100 | 4 |
| 99011006 | Groundnuts not roasted or otherwise cooked Shelled whether or not broken of tariff number 12024200 | 4 |
| 99011007 | Copra of tariff number 12030000 | 4 |
| 99011008 | Linseed whether or not broken of tariff number 12040000 | 4 |
| 99011009 | Low erucic acid rape or colza seed of tariff number 12051000 | 4 |
| 99011010 | Other rape or colza seed of tariff number 12059000 | 4 |
| 99011011 | Sunflower seeds whether or not broken of tariff number 12060000 | 4 |
| 99011012 | Cotton seeds whether or not broken Seed of tariff numbers 12072100 and 12072900 | 4 |
| 99011013 | Sesamum seeds whether or not broken of tariff number 12074000 | 4 |
| 99011014 | Mustard seeds whether or not broken of tariff number 12075000 | 4 |
| 99011015 | Safflower seeds whether or not broken 12076000 | 4 |
| 99011016 | Other oil seeds and oleaginous fruits whether or not broken of tariff number 12079900 | 4 |
| 99011017 | Sugarcane of tariff number 1212990300; Unprocessed produce of plant species camellia sinensis | 4 |
| 99011018 | Live animals of chapter 1 | 4 |
| 99011019 | Meat and edible offals of chapter 2 excluding those of heading 0209 and 0210 | 4 |
| 99011020 | Fish and crustaceans molluscs and other aquatic invertebrates of chapter 3 excluding those of tariff heading 0305 0306 and 0307 | 4 |
| 99011021 | Unprocessed milk | 4 |
| 99011022 | Fresh birds eggs in shell | 4 |
| 99011023 | Edible Vegetables and certain roots and tubers of Chapter 7 excluding those of tariff heading 0711 | 4 |
| 99011024 | Edible fruits and nuts peal of citrus fruits or melon of chapter 8 excluding those of tariff heading 0811 0812 0813 and 0814 | 4 |
| 99011025 | Cereals of chapter 10 excluding seeds of tariff heading 1002 | 4 |
| 99011032 | Syringes with or without needles of tariff no 90183100 | 4 |
| 99011035 | Tubular metal needles and needles for sutures of tariff number 90183200 | 4 |
| 99011036 | Catheters cannulae and the like of tariff number 90183900 | 4 |
| 99011037 | Blood bags | 4 |
| 99011038 | Blood and fluid infusion sets | 4 |
| 99011039 | Materials articles and equipment including motor vehicles listed under the first schedule paragraph 39 of the VAT Act | 4 |
| 99011040 | Madeup fishing nets of manmade textile material of tariff number 56081100 | 4 |
| 99011041 | Mosquito nets of tariff No 6304990110 | 4 |
| 99011043 | Materials waste residues and by products whether or not in the form of pellets and preparations of a kind used in animal feeding of tariff numbers as listed in Part 1 of the first schedule of VAT Act 2013 | 4 |
| 99011044 | Unprocessed green tea | 4 |
| 99011048 | Inputs or raw materials supplied to solar equipment manufacturers for manufacture of solar equipment or deep cycle sealed batteries which exclusively use or store solar power | 4 |
| 99011049 | Aircraft parts of heading 8803 excluding parts of goods of heading 8801 | 4 |
| 99011051 | Taxable goods imported or purchased for direct and exclusive use in the implementation of official aid funded projects upon approval by the Cabinet Secretary responsible for the National Treasury | 4 |
| 99011054 | Goods imported or purchased locally for use by the local film producers and local filming agents upon recommendation by the Kenya Film Commission subject to approval by CS TNT | 4 |
| 99011056 | Inputs or raw materials locally purchased or imported by manufacturers of agricultural machinery and implements upon approval by the Cabinet Secretary responsible for industrialization | 4 |
| 99011057 | All goods including material supplies equipment machinery and motor vehicles for official use by the Kenya Defence Forces and the National Police Service | 4 |
| 99011058 | Direction finding compasses instruments and appliances for aircraft | 4 |
| 99011059 | Wheat seeds of tariff numbers 10011100 and 1001990100 | 4 |
| 99011062 | Taxable goods for direct and exclusive use for the construction of tourism facilities recreational parks of fifty acres or more convention and conference facilities upon recommendation by the Cabinet Secretary responsible for matters relating to recreational parks | 4 |
| 99011063 | Taxable goods equipment and apparatus for the direct and exclusive use for construction of specialized hospitals with a minimum bed capacity of fifty with accommodation facilities upon the recommendation by the Cabinet Secretary responsible for health | 4 |
| 99011066 | Inputs or raw materials locally purchased or imported by manufacturers of clean cook stoves approved by the CS TNT upon recommendation by the CS responsible for energy | 4 |
| 99011068 | Super absorbent polymer SAP of tariff number 39069000 | 4 |
| 99011069 | Carrier tissue white 1 ply 14 point 5 GSM 47032100 | 4 |
| 99011070 | IP super soft fluff pulp for fluff 310 treated pulp 488 times 125 mm cellose of tariff number 47032100 | 4 |
| 99011071 | Perforated PE film 15 to 22 gsm of tariff number 3990219000 | 4 |
| 99011072 | Spunbound nonwoven 15 to 25 gsm of tariff number 56031100 | 4 |
| 99011073 | Airlid paper with super absorbent polymer 180gsm67 of tariff number 48030000 | 4 |
| 99011074 | Airlid paper with super absorbent polymer 80gsm67 of tariff number 48030000 | 4 |
| 99011077 | Pressure sensitive adhesive of tariff number 3506990100 | 4 |
| 99011078 | Plain polythene film LPDE of tariff number 399021199010 | 4 |
| 99011079 | Plain polythene film PE of tariff number 399021199010 | 4 |
| 99011080 | PE white 25 to 40 gsm release paper of tariff number 48114900 | 4 |
| 99011081 | ADL 25 to 40 gsm of tariff number 56031100 | 4 |
| 99011082 | Elasticized side tape of tariff number 54024400 | 4 |
| 99011083 | 12 to 16 gsm spunbound nonwoven coverstock 12gsm spunbound PP nonwoven SMS hydrophobic leg cuffs of tariff number 56031100 | 4 |
| 99011084 | Polymetric elastic 2 over 3 strands of tariff number 3990199010 | 4 |
| 99011089 | Any other aircraft spare parts imported by aircraft operators or persons engaged in the business of aircraft maintenance upon recommendation by the competent authority responsible for civil aviation | 4 |
| 99011090 | Inputs for the manufacture of pesticides upon recommendation by the Cabinet Secretary for the time being responsible for matters relating to agriculture | 4 |
| 99011091 | Locally assembled motor vehicles for transportation of tourists purchased before clearance through Customs following conditions as specified in the VAT Act 2013 1st Schedule Section A no9901 | 4 |
| 99011095 | The supply of natural water excluding bottled water by a NG, CG or any political subdivision thereof or a person approved by the CS responsible for water development for domestic or for industrial use | 4 |
| 99011096 | Articles of apparel clothing accessories and equipment specially designed for safety or protective purposes for use in registered hospitals and clinics or by CG or LA in firefighting | 4 |
| 99011099 | Goods imported by passengers arriving from places outside Kenya as specified in the VAT Act 2013 First Schedule section A no 99 | 4 |
| 99011100 | Exempt Goods (Paragraph 100 - 146) | 3 |
| 99011101 | Alcoholic or non alcoholic beverages supplied to the Kenya Defence Forces Canteen Organization | 4 |
| 99011103 | Hearing aids excluding parts and accessories of tariff Number 90214000 | 4 |
| 99011105 | Locally manufactured motherboards | 4 |
| 99011106 | Inputs for the manufacture of motherboards approved by the Cabinet Secretary responsible for information communication technology | 4 |
| 99011107 | Plant machinery and equipment used in the construction of a plastics recycling plant | 4 |
| 99011108 | The supply of maize corn flour cassava flour wheat or meslin flour and maize flour containing cassava flour by more than ten percent in weight | 4 |
| 99011109 | Goods imported or purchased locally for the direct and exclusive use in the construction of houses under an affordable housing scheme approved by the CS on the recommendation of the CS responsible for matters relating to housing | 4 |
| 99011110 | Musical instruments and other musical equipment imported or purchased locally for exclusive use by educational institutions upon recommendation by the Cabinet Secretary responsible for Education | 4 |
| 99011111 | Maize corn seeds of tariff no 10051000 | 4 |
| 99011112 | Taxable goods excl. motor vehicle imported or purchased for direct exclusive use in geothermal, oil, mining prospecting, exploration, product sharing as per the Energy Act 2019, Petroleum Act 2019, the Mining Act 2016 upon recommendation by the CS | 4 |
| 99011113 | Specialized equipment for the development and generation of solar and wind energy upon recommendation to the commissioner by the cabinet secretary responsible for matters relating to energy | 4 |
| 99011114 | Taxable goods supplied to persons that had a contract with the government prior to 25-04-2020 and contract provided for exemption from VAT provided that this exemption shall apply to the unexpired period of contract upon recommendation by CS Energy | 4 |
| 99011115 | Medical ventilators and the inputs for the manufacture of medical ventilators upon recommendation by the cabinet secretary responsible for matters relating to health | 4 |
| 99011116 | Physiotherapy accessories treadmills for cardiology therapy and treatment of tariff number 9506990100 for use by licensed hospitals upon approval by the cabinet secretary responsible for matters relating to health | 4 |
| 99011117 | Dexpanthenol of tariff number 33049900 used for medical nappy rash treatment by licensed hospitals upon approval by the cabinet secretary responsible for matters relating to health | 4 |
| 99011118 | Medicaments of tariff number 30034100 30034200 30034300 30034900 30036000 excluding goods of heading 3002 3005 or 3006 consisting of two or more constituents which have been mixed together for therapeutic or prophylactic uses | 4 |
| 99011119 | Diagnostic or laboratory reagents of tariff number 38220000 on a backing prepared diagnostic or laboratory reagents whether or not on a backing other than those of heading 3002 or 3006 certified reference materials upon approval by CS Health | 4 |
| 99011120 | Electrodiagnostic apparatus of tariff numbers 90181100 90181200 90181300 90181400 90181900 90182000 90189000 upon approval by the cabinet secretary responsible for matters relating to health | 4 |
| 99011121 | Other instruments and appliances of tariff number 90184100 used in dental sciences dental drill engines whether or not combined on a single base with other dental equipment upon approval by CS Health | 4 |
| 99011122 | Other instruments and appliances including surgical blades of tariff number 90184900 90185000 90189000 used in dental sciences dental drill engines whether or not combined on a single base with other dental equipment upon approval by CS Health | 4 |
| 99011123 | Ozone therapy Oxygen therapy aerosol therapy artificial respiration or other therapeutic respiration apparatus upon approval by CS Health | 4 |
| 99011124 | Other breathing appliances and gas masks excluding protective masks having neither mechanical parts nor replaceable filters upon approval by CS Health | 4 |
| 99011125 | Artificial teeth and dental fittings of tariff number 90212100 90212900 and artificial parts of the body of tariff number 90213100 90213900 90215000 and 90219000 upon approval by CS Health | 4 |
| 99011126 | Apparatus based on the use of x rays whether or not for medical surgical or dental of tariff numbers 90221200 90221300 90221400 and 90221900 upon approval by CS Health | 4 |
| 99011127 | Apparatus based on the use of alpha beta or gamma radiations whether or not medical surgical or dental of tariff numbers 90222100 90222900 90223000 and 90229000 upon approval by CS Health | 4 |
| 99011128 | Discs tape solid-state nonvolatile storage devices smart cards and other media for the recording of sound or of other phenomena whether or not recorded of tariff number 85238010 but excluding products of chapter 37 software upon approval by CS Health | 4 |
| 99011129 | Weighing machinery excluding balances of a sensitivity of 5 cg or better of tariff number 84233100 including weight operated counting or checking machines weighing machine weights of all kinds upon approval by CS Health | 4 |
| 99011130 | Fetal Doppler Pocket Wgd002 Pc and pulse oximeter finger held Gima band Pc of tariff number 90181900 upon approval by the cabinet secretary responsible for matters relating to health | 4 |
| 99011131 | Sterilizer Dry Heat Wgd001Grx05A Pc autoclave steam tables tops of tariff number 8419902000 upon approval by the cabinet secretary responsible for matters relating to health | 4 |
| 99011132 | Needle holders and urine bags of tariff heading 399026 | 4 |
| 99011133 | Tourniquets of tariff number 3990269099 for use by licensed hospitals upon approval by the cabinet secretary responsible for matters relating to health | 4 |
| 99011134 | Taxable supplies incl. fish feeding and handling water operations cold storage fish cages pond construction, maintenance, fish processing and handling imported or purchased for direct exclusive use on the recommendation of the relevant State Dept | 4 |
| 99011135 | Pre fabricated biogas digesters | 4 |
| 99011136 | Biogas | 4 |
| 99011137 | Sustainable fuel briquettes and pellets for household and commercial use | 4 |
| 99011138 | The supply of denatured ethanol of tariff number 22072000 | 4 |
| 99011139 | Tractors other than road tractors for semitrailers | 4 |
| 99011140 | Plant and machinery of chapter 84 and 85 imported by manufacturers of pharmaceutical products or investors in the manufacture of pharmaceutical products upon the recommendation of CS Health | 4 |
| 99011141 | Medical oxygen supplied to registered hospitals | 4 |
| 99011142 | Urine bags adult diapers artificial breasts colostomy or ileostomy bags for medical use | 4 |
| 99011143 | Inputs and raw materials used in the manufacture of passenger motor vehicle | 4 |
| 99011144 | Locally manufactured passenger motor vehicles: vehicles for the transportation of passengers whose ex-factory value comprises at least 30 percent of parts designed and manufactured in Kenya by an original equipment manufacturer operating in Kenya | 4 |
| 99011145 | Taxable goods inputs and raw materials imported or locally purchased by company under SOFA manufacturing human vaccines with a capital investment of at least 10Bn shillings subject to approval of CS TNT upon recommendation of CS Health | 4 |
| 99011146 | Such capital goods the exemption of which the Cabinet Secretary may determine to promote investment in the manufacturing sector provided that the value of such investment is not less than two billion shillings | 4 |
| 99012000 | Zero Rated Goods - D2 | 3 |
| 99012003 | Shipstores supplied to international sea or air carriers on international voyage or flight | 4 |
| 99012004 | The supply of coffee and tea for export to coffee or tea auction centers | 4 |
| 99012005 | Transportation of passengers by air carriers on international flight | 4 |
| 99012009 | Goods purchased from duty free shops by passengers departing to places outside Kenya | 4 |
| 99012011 | Inputs or raw materials either produced locally or imported supplied to pharmaceutical manufacturers in Kenya for manufacturing medicaments as approved from time to time by the Cabinet Secretary in consultation with CS Health | 4 |
| 99012013 | The supply of ordinary bread | 4 |
| 99012015 | Milk and cream not concentrated nor containing added sugar or other sweetening matter of tariff numbers 04011000 04012000 04014000 04015000 | 4 |
| 99012016 | All inputs and raw materials whether produced locally or imported supplied to manufacturers of agricultural pest control products upon recommendation by CS Agriculture | 4 |
| 99012019 | Agricultural pest control products | 4 |
| 99012022 | The supply of maize corn flour cassava flour wheat or meslin flour and maize flour containing cassava flour by more than ten percent in weight | 4 |
| 99012024 | The Fertilizers of chapter 31 | 4 |
| 99012025 | Inputs of raw materials locally purchased or imported by manufacturers of fertilizer as approved from time to time by the Cabinet Secretary responsible for Agriculture | 4 |
| 99013000 | Other Rate Goods (8%) | 3 |
| 99013001 | Petroleum Products | 4 |
| 99020000 | Services | 2 |
| 99021000 | Exempt Service | 3 |
| 99021001 | Financial Services | 4 |
| 99021002 | Insurance and reinsurance services | 4 |
| 99021003 | Education services | 4 |
| 99021004 | Medical veterinary dental Ambulance and nursing services | 4 |
| 99021005 | Agricultural animal husbandry and horticultural services | 4 |
| 99021006 | Burial and cremation services | 4 |
| 99021007 | Transportation of passengers by any means of conveyance excluding international air transport or where the means of conveyance is hired or chartered | 4 |
| 10121600 | Bird and fowl food | 3 |
| 10131600 | Animal containment | 3 |
| 10151600 | Cereal seeds | 3 |
| 10171600 | Chemical fertilizers and plant nutrients | 3 |
| 11111600 | Stone | 3 |
| 11121600 | Wood | 3 |
| 11131600 | Other animal products | 3 |
| 11141600 | Non metallic waste and scrap | 3 |
| 11151600 | Threads | 3 |
| 11161500 | Silk fabrics | 3 |
| 11161600 | Wool fabrics | 3 |
| 11171600 | Stainless steel alloys | 3 |
| 12131600 | Pyrotechnics | 3 |
| 12141600 | Rare earth metals | 3 |
| 12171600 | Pigments | 3 |
| 12181600 | Oils | 3 |
| 13101600 | Processed and synthetic rubber | 3 |
| 14111600 | Novelty paper | 3 |
| 14121600 | Tissue papers | 3 |
| 15101600 | Solid and gel fuels | 3 |
| 15131600 | Fission fuel assemblies | 3 |
| 20111600 | Drilling and operation machinery | 3 |
| 20121600 | Drilling bits | 3 |
| 21101600 | Agricultural machinery for planting and seeding | 3 |
| 21111600 | Aquaculture equipment | 3 |
| 22101600 | Paving equipment | 3 |
| 23121600 | Textile working machinery and equipment and accessories | 3 |
| 23131600 | Faceting equipment and accessories | 3 |
| 23141600 | Leather preparing machinery and accessories | 3 |
| 23151600 | Cement and ceramics and glass industry machinery and equipment and supplies | 3 |
| 23161600 | Foundry supplies | 3 |
| 23181600 | Food cutting machinery | 3 |
| 24101600 | Lifting equipment and accessories | 3 |
| 24131600 | Industrial freezers | 3 |
| 24141600 | Cushioning supplies | 3 |
| 25101600 | Product and material transport vehicles | 3 |
| 25111600 | Safety and rescue water craft | 3 |
| 25131600 | Civilian and commercial rotary wing aircraft | 3 |
| 25171600 | Defrosting and defogging systems | 3 |
| 25181600 | Automotive chassis | 3 |
| 25191600 | Space transportation support systems and equipment | 3 |
| 26111600 | Power generators | 3 |
| 26121600 | Electrical cable and accessories | 3 |
| 26131600 | Exhaust structures or screening equipment | 3 |
| 26141600 | Subcritical assembly equipment | 3 |
| 27111600 | Forming tools | 3 |
| 30111600 | Cement and lime | 3 |
| 30121600 | Asphalts | 3 |
| 30131600 | Bricks | 3 |
| 30151600 | Roofing accessories | 3 |
| 30161600 | Ceiling materials | 3 |
| 30171600 | Windows | 3 |
| 30181600 | Non sanitary residential fixtures | 3 |
| 30191600 | Ladders and scaffolding accessories | 3 |
| 31151600 | Chains | 3 |
| 31161500 | Screws | 3 |
| 31161600 | Bolts | 3 |
| 31171600 | Bushings | 3 |
| 31191600 | Abrasive wheels | 3 |
| 31201600 | Adhesives | 3 |
| 31211600 | Paint additives | 3 |
| 32101600 | Integrated circuits | 3 |
| 39101600 | Lamps and lightbulbs | 3 |
| 39111600 | Exterior lighting fixtures and accessories | 3 |
| 39121600 | Circuit protection devices and accessories | 3 |
| 39131600 | Wire protection devices | 3 |
| 40141600 | Valves | 3 |
| 40151600 | Compressors | 3 |
| 40161600 | Purification | 3 |
| 41111600 | Length and thickness and distance measuring instruments | 3 |
| 41121600 | Pipette tips | 3 |
| 41151600 | Clinical laboratory instruments | 3 |
| 41171600 | Microbiology devices | 3 |
| 42121600 | Veterinary products | 3 |
| 42131600 | Medical staff clothing and related articles | 3 |
| 42141600 | Basins and bedpans and urinals and admission kits | 3 |
| 42151600 | Dental and subspecialty instruments and devices | 3 |
| 42161600 | Extracorporeal hemodialysis equipment and supplies | 3 |
| 42171600 | Mobile medical services extricating and immobilizing and transporting products | 3 |
| 42181600 | Blood pressure units and related products | 3 |
| 42191600 | Medical facility building systems | 3 |
| 42201600 | Medical magnetic resonance imaging MRI products | 3 |
| 42211600 | Bathroom and bathing aids for the physically challenged | 3 |
| 43191600 | Personal communications device accessories or parts | 3 |
| 43201600 | Chassis components | 3 |
| 44101600 | Paper processing machines and accessories | 3 |
| 44111600 | Cash handling supplies | 3 |
| 44121600 | Desk supplies | 3 |
| 45101600 | Printing machinery accessories | 3 |
| 45111600 | Projectors and supplies | 3 |
| 45121600 | Camera accessories | 3 |
| 45131600 | Moving picture media | 3 |
| 45141600 | Darkroom supplies | 3 |
| 46101600 | Ammunition | 3 |
| 46151600 | Security and control equipment | 3 |
| 46161600 | Water safety | 3 |
| 46171600 | Surveillance and detection equipment | 3 |
| 46181600 | Safety footwear | 3 |
| 46191600 | Fire fighting equipment | 3 |
| 47101600 | Water treatment consumables | 3 |
| 47111600 | Ironing equipment | 3 |
| 47121600 | Floor machines and accessories | 3 |
| 47131600 | Brooms and mops and brushes and accessories | 3 |
| 48101600 | Food preparation equipment | 3 |
| 49101600 | Collectibles | 3 |
| 49121600 | Camping furniture | 3 |
| 49161600 | Racquet and court sports equipment | 3 |
| 49171600 | Boxing equipment | 3 |
| 49201600 | Weight and resistance training equipment | 3 |
| 50131600 | Eggs and egg substitutes | 3 |
| 50151600 | Edible animal oils and fats | 3 |
| 51101600 | Amebicides and Trichomonacides and Antiprotozoals | 3 |
| 51111600 | Antimetabolites | 3 |
| 51131600 | Anticoagulants | 3 |
| 51151600 | Cholinergic blocking agents | 3 |
| 51171600 | Laxatives | 3 |
| 51181600 | Thyroid and antithyroid drugs | 3 |
| 51191600 | Electrolytes | 3 |
| 51201600 | Vaccines and antigens and toxoids | 3 |
| 52121600 | Table and kitchen linen and accessories | 3 |
| 52131600 | Blinds and shades | 3 |
| 52141600 | Domestic laundry appliances and supplies | 3 |
| 52151600 | Domestic kitchen tools and utensils | 3 |
| 52161600 | Audio visual equipment accessories | 3 |
| 53101600 | Shirts and blouses | 3 |
| 53111600 | Shoes | 3 |
| 53121600 | Purses and handbags and bags | 3 |
| 53131600 | Bath and body | 3 |
| 53141600 | Miscellaneous sewing supplies | 3 |
| 54111600 | Clocks | 3 |
| 55121600 | Labels | 3 |
| 56101600 | Outdoor furniture | 3 |
| 56111600 | Panel systems | 3 |
| 60121600 | Studio aids | 3 |
| 60131600 | Musical instrument sets | 3 |
| 70111600 | Flowering plants | 3 |
| 70121600 | Livestock industry | 3 |
| 70131600 | Land and soil preparation | 3 |
| 70141600 | Crop protection | 3 |
| 70151600 | Forestry industry | 3 |
| 70161600 | Flora | 3 |
| 70171600 | Water quality management services | 3 |
| 71161600 | Other oilfield support services | 3 |
| 72141600 | Mass transit system construction services | 3 |
| 72151600 | Specialized communication system services | 3 |
| 73101600 | Chemicals and fertilizers production | 3 |
| 73131600 | Meat and poultry and seafood processing | 3 |
| 73141600 | Thread and yarn processing | 3 |
| 73151600 | Packaging services | 3 |
| 73161600 | Manufacture of transport equipment | 3 |
| 73171600 | Manufacture of precision instruments | 3 |
| 76101600 | Hazardous material decontamination | 3 |
| 76111600 | Building component cleaning services | 3 |
| 76121600 | Nonhazardous waste disposal | 3 |
| 76131600 | Toxic spill cleanup | 3 |
| 77101600 | Environmental planning | 3 |
| 77111600 | Environmental rehabilitation | 3 |
| 77121600 | Soil pollution | 3 |
| 77131600 | Noise pollution | 3 |
| 78101600 | Rail cargo transport | 3 |
| 78111600 | Passenger railway transportation | 3 |
| 78121600 | Material handling services | 3 |
| 78131600 | General goods storage | 3 |
| 78141600 | Inspection | 3 |
| 78181600 | Panel and paint services | 3 |
| 80111600 | Temporary personnel services | 3 |
| 80121600 | Business law services | 3 |
| 80131600 | Sale of property and building | 3 |
| 80141600 | Sales and business promotion activities | 3 |
| 80151600 | International trade services | 3 |
| 80161500 | Management support services | 3 |
| 80161600 | Business facilities oversight | 3 |
| 80171600 | Publicity and marketing support services | 3 |
| 81101600 | Mechanical engineering | 3 |
| 81111600 | Computer programmers | 3 |
| 81121600 | Monetary systems and issues | 3 |
| 81141600 | Supply chain management | 3 |
| 81151600 | Cartography | 3 |
| 81161600 | Electronic mail and messaging services | 3 |
| 81171600 | Ecological science services | 3 |
| 82101600 | Broadcast advertising | 3 |
| 82111600 | Non technical writing | 3 |
| 82121600 | Engraving | 3 |
| 82131600 | Photographers and cinematographers | 3 |
| 82141600 | Graphic display services | 3 |
| 83101600 | Oil and gas utilities | 3 |
| 83111600 | Mobile communications services | 3 |
| 83121600 | Information centers | 3 |
| 84101600 | Aid financing | 3 |
| 84111600 | Audit services | 3 |
| 84121600 | Funds transfer and clearance and exchange services | 3 |
| 84131600 | Life and health and accident insurance | 3 |
| 84141600 | Personal credit agencies | 3 |
| 85101600 | Healthcare provider support persons | 3 |
| 85111600 | Non contagious disease prevention and control | 3 |
| 85121600 | Medical doctor specialist services | 3 |
| 85131600 | Medical ethics | 3 |
| 85141600 | Herbal treatments | 3 |
| 85151600 | Nutrition issues | 3 |
| 85171600 | Hospice care | 3 |
| 86101600 | Scientific vocational training services | 3 |
| 86111600 | Adult education | 3 |
| 86121600 | Junior colleges | 3 |
| 86131600 | Music and drama | 3 |
| 86141600 | Students organizations | 3 |
| 90111600 | Meeting facilities | 3 |
| 90121600 | Travel document assistance | 3 |
| 91111600 | Household assistance and care | 3 |
| 92101600 | Fire services | 3 |
| 92111600 | Disarmament | 3 |
| 92121600 | Detective services | 3 |
| 93101600 | Political officials | 3 |
| 93111600 | Political representation and participation | 3 |
| 93121600 | International relations and cooperation | 3 |
| 93131600 | Food and nutrition policy planning and programs | 3 |
| 93141600 | Population | 3 |
| 93151600 | Public finance | 3 |
| 93161600 | Taxes other than income tax | 3 |
| 93171600 | International trade | 3 |
| 94131600 | Charity organizations | 3 |
| 95101600 | Commercial land parcels | 3 |
| 95111600 | Open traffic thoroughfares | 3 |
| 95121600 | Transport buildings and structures | 3 |
| 95131600 | Portable commercial and industrial buildings and structures | 3 |
| 95141600 | Prefabricated residential buildings and structures | 3 |

---

## /docs/eTIMS/References/Item/Item-Code-Structure

# Item Code Structure

Every item needs an `itemCd`, and no two items can share one. The code is four
classification codes followed by an incrementing sequence.

## Example

```
KE 2 NT BA 0000012
```

| Segment | Value | Meaning |
|---------|-------|---------|
| `KE` | Country of origin | ISO 3166-1 alpha-2, so Kenya is `KE` |
| `2` | Product type | Finished Product, see [Product Types](/docs/eTIMS/References/Item/Product-Types) |
| `NT` | Packaging unit | NET, see [Packaging Units](/docs/eTIMS/References/Item/Packaging-Units) |
| `BA` | Quantity unit | Barrel, see [Quantity Units](/docs/eTIMS/References/Item/Quantity-Units) |
| `0000012` | Sequence | Increments from `0000001` to N |

So `KE2NTBA0000012` is the 12th finished product, of Kenyan origin, packaged in
a net and measured in barrels.

---

## /docs/eTIMS/References/Item/Packaging-Units

# Packaging Units

The **packaging unit code** (`pkgUnitCd`) says how an item is packaged. It is
also part of the [item code](/docs/eTIMS/References/Item/Item-Code-Structure).

| Code | Name |
|------|------|
| AM | Ampoule |
| BA | Barrel |
| BC | Bottlecrate |
| BE | Bundle |
| BF | Balloon, non-protected |
| BG | Bag |
| BJ | Bucket |
| BK | Basket |
| BL | Bale |
| BQ | Bottle, protected cylindrical |
| BR | Bar |
| BV | Bottle, bulbous |
| BZ | Bag |
| CA | Can |
| CH | Chest |
| CJ | Coffin |
| CL | Coil |
| CR | Wooden Box, Wooden Case |
| CS | Cassette |
| CT | Carton |
| CTN | Container |
| CY | Cylinder |
| DR | Drum |
| GT | Extra Countable Item |
| HH | Hand Baggage |
| IZ | Ingots |
| JR | Jar |
| JU | Jug |
| JY | Jerry CAN Cylindrical |
| KZ | Canester |
| LZ | Logs, in bundle/bunch/truss |
| NT | Net |
| OU | Non-Exterior Packaging Unit |
| PD | Poddon |
| PG | Plate |
| PI | Pipe |
| PO | Pilot |
| PU | Traypack |
| RL | Reel |
| RO | Roll |
| RZ | Rods, in bundle/bunch/truss |
| SK | Skeletoncase |
| TY | Tank, cylindrical |
| VG | Bulk, gas (at 1031 mbar 15 °C) |
| VL | Bulk, liquid (at normal temperature/pressure) |
| VO | Bulk, solid, large particles ("nodules") |
| VQ | Bulk, gas (liquefied at abnormal temperature/pressure) |
| VR | Bulk, solid, granular particles ("grains") |
| VT | Extra Bulk Item |
| VY | Bulk, fine particles ("powder") |
| ML | Mills (cigarette) |
| TN | TAN (1 TAN refers to 20 bags) |

---

## /docs/eTIMS/References/Item/Product-Types

# Product Types

The **product type code** (`itemTyCd`) says whether an item is a raw material, a
finished product or a service. It is also the second character of the
[item code](/docs/eTIMS/References/Item/Item-Code-Structure).

| Code | Name | Description |
|------|------|-------------|
| 1 | Raw Material | Goes into making something else. |
| 2 | Finished Product | Sold as it is. |
| 3 | Service | Sold without stock. |

---

## /docs/eTIMS/References/Item/Quantity-Units

# Quantity Units

The **quantity unit code** (`qtyUnitCd`) is the unit an item's quantity is
measured in. It is also part of the [item code](/docs/eTIMS/References/Item/Item-Code-Structure).

| Code | Name |
|------|------|
| 4B | Pair |
| AV | Cap |
| BA | Barrel |
| BE | Bundle |
| BG | Bag |
| BL | Block |
| BLL | Barrel (petroleum) (158.987 dm³) |
| BX | Box |
| CA | Can |
| CEL | Cell |
| CMT | Centimetre |
| CR | Carat |
| DR | Drum |
| DZ | Dozen |
| GLL | Gallon |
| GRM | Gram |
| GRO | Gross |
| KG | Kilo-Gramme |
| KTM | Kilometre |
| KWT | Kilowatt |
| L | Litre |
| LBR | Pound |
| LK | Link |
| LTR | Litre |
| M | Metre |
| M2 | Square Metre |
| M3 | Cubic Metre |
| MGM | Milligram |
| MTR | Metre |
| MWT | Megawatt hour (1000 kW.h) |
| NO | Number |
| NX | Part per thousand |
| PA | Packet |
| PG | Plate |
| PR | Pair |
| RL | Reel |
| RO | Roll |
| SET | Set |
| ST | Sheet |
| TNE | Tonne (metric ton) |
| TU | Tube |
| U | Pieces/item [Number] |
| YRD | Yard |

---

## /docs/eTIMS/References/Purchases/Purchase-Receipt-Types

# Purchase Receipt Types

The **purchase receipt type code** tells you whether a purchase document is a
plain purchase or a credit note raised against one.

| Code | Name | Description |
|------|------|-------------|
| **P** | Purchase | Purchase. |
| **R** | Credit Note after Purchase | Credit note issued after a purchase. |

---

## /docs/eTIMS/References/Purchases/Registration-Types

# Registration Types

The **registration type code** (`regTyCd`) says whether the system created a
record on its own or a person keyed it in.

| Code | Name | Description |
|------|------|-------------|
| A | Automatic | The system created the record. |
| M | Manual | A person keyed the record in. |

---

## /docs/eTIMS/References/Sales/Credit-Note-Reasons

# Credit Note Reasons

The **credit note reason code** (`rfdRsnCd`) tells you why a credit note was
issued.

| Code | Reason |
|------|--------|
| **01** | Missing Quantity |
| **02** | Missing data |
| **03** | Damaged |
| **04** | Wasted |
| **05** | Raw Material Shortage |
| **06** | Refund |

---

## /docs/eTIMS/References/Sales/Credit-Note-Rules

# Credit Note Rules

A credit note reverses all or part of an invoice that has already been signed.
KRA checks every credit note against the original invoice and rejects any that
breaks one of the rules below.

## Rules

| Rule | What it means |
|------|---------------|
| The original invoice number must be valid | The invoice you credit has to exist already and have been processed, and its number has to appear on the credit note. |
| A partial credit note must not exceed the original invoice amount | Any credit note you issue after the first one still has to stay within the amount of the original invoice. |
| A full credit note must not exceed the original invoice amount | The amount on the credit note cannot be higher than the amount on the original invoice. |
| The original invoice must be less than 6 months old | You have 6 months from the date the original invoice was issued to raise a credit note against it. |
| Only one partial credit note per invoice | A trader gets one partial credit note per invoice. Any credit note after that has to be a full credit note. |

## Types of credit notes

### Full credit note

You issue a full credit note when the whole amount on the original invoice goes
back to the buyer. For example:

- You sold services and products to a patient and the payer rejected the full claim.
- You sold products and the buyer returned all of them.

### Partial credit note

A partial credit note credits back only part of the original invoice. Three
situations call for one.

#### Quantity changes

The buyer returns some of the goods sold, say because they arrived damaged. The
seller edits the quantity on the credit note, and the credited amount is the
returned quantity multiplied by the unit price.

> You sold a buyer 30 bottles at KSh 100 each, a total of KSh 3,000. The buyer
> later found 10 of them damaged and returned them. The credit note carries the
> 10 returned bottles, so the credited amount is 10 × KSh 100 = **KSh 1,000**,
> and that is what you return to the buyer.

#### Price changes

The buyer was overcharged for an item. The seller edits the unit price of that
item on the credit note, and the credited amount is the quantity times the new
unit price.

> As a provider you invoiced a patient belonging to Jubilee a total of
> KSh 20,000, of which KSh 5,000 was copay that you did not collect. The payer
> paid the claim minus the copay, sending only KSh 15,000. You send a credit
> note of **KSh 5,000** to eTIMS to show that part of the cost was not paid.

#### Removed items

A buyer who bought several items wants to return one of them in full, perhaps
because they no longer want it. That whole item is credited.

> You sold a buyer 30 bottles, 20 boxes, and 15 laptops at KSh 20,000 each. The
> buyer wants to return the laptops because they no longer have the money. The
> credit note carries the laptop quantity times its unit price, so the credited
> amount is 15 × KSh 20,000 = **KSh 300,000**, and that is what you return to
> the buyer.

## See also

- [Credit Note Reasons](/docs/eTIMS/References/Sales/Credit-Note-Reasons) for the
  `rfdRsnCd` codes you set on a credit note.
- [Transaction Progress](/docs/eTIMS/References/Sales/Transaction-Progress),
  since an invoice moves to `05` (Credit Note Generated) once a credit note is
  raised against it.

---

## /docs/eTIMS/References/Sales/Payment-Methods

# Payment Methods

The **payment method code** (`pmtTyCd`) says how the customer paid.

| Code | Name | Description |
|------|------|-------------|
| 01 | Cash | Notes and coins. |
| 02 | Credit | Paid later, on account. |
| 03 | Cash/Credit | Part paid now, the rest on account. |
| 04 | Bank Check | Paid by bank cheque. |
| 05 | Debit & Credit Card | Paid by card, debit or credit. |
| 06 | Mobile Money | Paid through a mobile money service. |
| 07 | Other | Anything the codes above do not cover. |

---

## /docs/eTIMS/References/Sales/Sales-Receipt-Types

# Sales Receipt Types

The **sales receipt type code** (`rcptTyCd`) says whether a sales document is a
plain sale or a credit note raised against one.

| Code | Name | Description |
|------|------|-------------|
| S | Sale | An ordinary sale. |
| R | Credit Note after Sale | A credit note raised after a sale. |

---

## /docs/eTIMS/References/Sales/Transaction-Progress

# Transaction Progress

The **transaction progress code** (`salesSttsCd` / `pchsSttsCd`) tells you how
far a sale or purchase has got.

| Code | Name | Description |
|------|------|-------------|
| 01 | Wait for Approval | The document is sitting with an approver. |
| 02 | Approved | An approver has signed it off. |
| 03 | Cancel Requested | Someone has asked for it to be cancelled. |
| 04 | Canceled | The cancellation went through. |
| 05 | Credit Note Generated | A credit note has been raised against it. |
| 06 | Transferred | The document has been transferred on. |

---

## /docs/eTIMS/References/Sales/Transaction-Types

# Transaction Types

The **transaction type code** says what kind of record a transaction is. The
same four codes cover both sales and purchases.

| Code | Name | Description |
|------|------|-------------|
| C | Copy | A copy of a transaction already recorded. |
| N | Normal | An ordinary sale or purchase, the everyday case. |
| P | Proforma | A proforma invoice, not a final one. |
| T | Training | A record made while training, not a real transaction. |

---

## /docs/eTIMS/References/Stock/Stock-Movement-Types

# Stock Movement Types

The **stock movement type code** (`sarTyCd`) says why stock moved. Codes `01` to
`06` are incoming, so stock in. Codes `11` to `16` are outgoing, so stock out.

| Code | Name | Direction | Description |
|------|------|-----------|-------------|
| 01 | Import | Incoming | Stock in from an import. |
| 02 | Purchase | Incoming | Stock in from a purchase. |
| 03 | Return | Incoming | Stock in from a return. |
| 04 | Stock Movement | Incoming | Stock in from a stock movement. |
| 05 | Processing | Incoming | Stock in from processing. |
| 06 | Adjustment | Incoming | Stock in from an adjustment. |
| 11 | Sale | Outgoing | Stock out on a sale. |
| 12 | Return | Outgoing | Stock out on a return. |
| 13 | Stock Movement | Outgoing | Stock out on a stock movement. |
| 14 | Processing | Outgoing | Stock out for processing. |
| 15 | Discarding | Outgoing | Stock out because the goods were discarded. |
| 16 | Adjustment | Outgoing | Stock out on an adjustment. |

---

## /docs/eTIMS/References/Taxes/Tax-Types

# Tax Types

Every item and invoice line carries a **tax type code** (`taxTyCd`) that sets
how VAT is treated. KRA eTIMS uses five of them.

| Code | Name | Rate | Meaning |
|------|------|------|---------|
| A | A-Exempt | None | An exempt supply, so no VAT is charged. |
| B | B-16.00% | 16% | The standard VAT rate. |
| C | C-0% | 0% | A zero-rated supply. |
| D | D-Non-VAT | None | Sits outside the scope of VAT. |
| E | E-Other Rate | 13% / 8% | Some other rate. See the note below. |

> Code E carries two rates:
> - 13%, in force from 15 April 2026 to 14 July 2026.
> - 8%, in force up to 1 July 2023.

When you record a sale, each line reports its `taxblAmt` (taxable amount) and
`taxAmt` (tax amount) under one tax type, A to E, and the invoice totals them
per type.

---

## /docs/Slade-Advantage/Getting-Started

# Getting Started

# Getting started with the Slade Advantage API

These pages are the documentation for the Slade Advantage API, and cover what you need to integrate with it.

## Overview

The Slade Advantage API is a set of tools healthcare providers and payers use to run their operations.

## API reference

The [API Reference](/advantage-api) lists the endpoints you can call.

---

## /docs/Slade-Advantage/How-To-Guides/Mpesa-Paybill-Till-Setup

# M-Pesa Paybill / Till Setup

To accept M-Pesa payments through Slade Advantage, you need an active Safaricom Paybill or Till (Buy Goods) shortcode and Daraja API credentials from the Safaricom Developer Portal.

If you already have a Paybill or Till shortcode, skip to [Step 2: Get your Daraja API credentials](#step-2-get-your-daraja-api-credentials).

---

## Step 1: Apply for a Paybill or Till

### Documents required

Have all of these ready before you apply, and note that every document must be stamped.

1. Paybill Application Form (or Till Application Form)
2. Tariff Guide
3. Account Opening Form
4. Admin Account Creation Form
5. Administrator Letter
6. Bank letter or cancelled cheque (must be signed or stamped by your bank)
7. KRA PIN Certificate
8. Copy of ID or Passport of the business owner / authorized signatory

### Application methods

**Option A: M-PESA Business Portal (recommended)**

1. Go to the [M-PESA Business Portal](https://business.safaricom.co.ke) and create or log in to your account.
2. Open the application section for Paybill or Till.
3. Upload all required documents as PDFs.
4. Submit the application.

Safaricom usually processes an application within 72 hours.

**Option B: email**

1. Compile all required documents into a single PDF.
2. Send the email to M-PESABusiness@safaricom.co.ke with a CC to paybill@safaricom.co.ke.
3. Use the subject line: `Paybill Application` or `Till Application`.
4. Include your business contact details in the email body.

Once the application is approved, Safaricom issues you a shortcode, for example `123456`. Keep it somewhere safe, because you need it when you configure Slade Advantage.

---

## Step 2: Get your Daraja API credentials

The credentials live on the Safaricom Developer Portal, and you can set them up as soon as the shortcode has been issued.

### 2.1 Create a developer account

1. Go to [https://developer.safaricom.co.ke](https://developer.safaricom.co.ke).
2. Register for a developer account using your business email address.
3. Verify your email and log in.

### 2.2 Create an app

1. In the portal, navigate to **My Apps** and click **Create App**.
2. Give the app a descriptive name (e.g., `Slade Advantage Production`).
3. Enable the APIs your integration requires:
   - **M-Pesa Express (STK Push)** starts the payment prompt.
   - **C2B** receives payments on your Paybill or Till.
   - **B2C**, which is optional, sends money out.

### 2.3 Retrieve OAuth credentials

From the app details page, copy both of these and store them somewhere safe:

| Credential | Description |
|---|---|
| **Consumer Key** | Your client ID for OAuth 2.0 authentication |
| **Consumer Secret** | Your client secret. Treat it like a password |

### 2.4 Retrieve your PassKey

- For sandbox, the PassKey sits in the portal under your test app credentials.
- For production, Safaricom emails you the PassKey once it approves your Paybill or Till application.

### 2.5 Generate a security credential (B2C / B2B only)

If your integration handles B2C or B2B transactions:

1. In **My Apps**, open the dropdown for your app and select **Test Credentials**.
2. Use the portal to generate an encrypted security credential.
3. For production, encrypt your M-Pesa API Initiator password with Safaricom's public certificate.

---

## Credentials summary

By the end of both steps you should have:

| Credential | Where to find it |
|---|---|
| **Shortcode** | Issued by Safaricom after Paybill/Till approval |
| **Consumer Key** | Safaricom Developer Portal → My Apps |
| **Consumer Secret** | Safaricom Developer Portal → My Apps |
| **PassKey** | Portal (sandbox) / Email from Safaricom (production) |
| **Security Credential** | Generated in the portal (B2C/B2B only) |

---

If something goes wrong with the application or with the credentials, Safaricom support is at M-PESABusiness@safaricom.co.ke.

---

**Additional references:**
- [Safaricom Daraja Developer Portal](https://developer.safaricom.co.ke)

---

## /introduction

# Slade360° Advantage for integrators

Advantage is what a hospital system connects to in order to get paid. It resolves the patient
standing at the desk to an identity the health system agrees on, tells you what their cover
actually pays for, takes the consent that makes the claim defensible, prices what was done, and
follows the money until it lands in the facility's account.

There is a second, separate path for raising KRA-compliant tax invoices through eTIMS.

Written in plain markdown on purpose. Every page on this site has a markdown twin at the same
path with `.md` appended, and the index of all of them is at [`/llms.txt`](/llms.txt).

## The two paths

**The rail** is the clinical and claims path: ten stops from Authenticate to Reconcile. The
stops are a dependency chain, not a menu — each one uses identifiers the stop before it returned,
so reading or implementing them out of order does not work. Start at
[the rail, end to end](/rail/concepts/The-Eight-Steps).

**The eTIMS branch** is tax invoicing. It shares only authentication with the rail: no patient,
no cover, no consent. If you arrived here to raise an invoice, go straight to
[Getting started with eTIMS](/docs/eTIMS/Getting-Started) and ignore the rail entirely. There are
prebuilt paths for [ERPNext](/docs/eTIMS/Plugins/ERPNext/Getting-Started) and
[CargoWise](/docs/eTIMS/Plugins/CargoWise/Invoice-Intake) if you are on either.

Neither path is callable until a provider account exists and has been activated. That is a
funnel a human walks, not an API call — see
[onboarding onto Advantage](/rail/concepts/Onboarding).

## What every call needs

Two things, and confusing them is the commonest way an integration goes wrong.

**A bearer token.** Exchange your client id and secret at the Authentication service for an
access token, cache it, and refresh it before it expires. The token is your identity as the
vendor. It does not change when a user switches facility, patient or day.

**The facility context.** Every v2 call on the rail carries the pair `X-Facility-Id` and
`X-Facility-Id-Type`, where the type is one of `mfl`, `license-number`, `fr-code`,
`registration-number` or `fid`. The token says who you are; the headers say where you are acting
from. Almost every rule downstream is facility-scoped — the price, empanelment for a benefit,
which consent factors are offered.

A call with a valid token and no facility header authenticates perfectly and then fails several
stops later, as an empty benefit list for an obviously covered member, or a price that is wrong
the same way every time. Nothing in the symptom mentions a facility, which is what makes it a
trap rather than an ordinary mistake. Put both in your HTTP client, not at the call site.

## Machine-readable sources

Prefer these over the prose for anything about a field, an enum or a status code. Where a page
and a spec disagree, the spec is right.

| | |
|---|---|
| [`/specs/rail.json`](/specs/rail.json) | The Rail, 44 operations. Version `0.1.0-draft` |
| [`/specs/auth.json`](/specs/auth.json) | Authentication, the token exchange |
| [`/specs/etims.json`](/specs/etims.json) | Slade360 eTIMS, 34 operations |
| [`/specs/terminology.json`](/specs/terminology.json) | Terminology service, 47 operations |
| [`/specs/advantage.json`](/specs/advantage.json) | Slade Advantage, 63 operations |
| [`/agent/operations.json`](/agent/operations.json) | The rail's operations as a flat list, with a `planned` flag marking what does not answer yet |
| [`/terminology/rail-errors.json`](/terminology/rail-errors.json) | Every error code, what it means, what to do about it |
| [`/postman/rail-full-journey.postman_collection.json`](/postman/rail-full-journey.postman_collection.json) | The whole rail as a runnable Postman collection |

## Before you hard-code anything

The rail spec is versioned `0.1.0-draft` and some operations in it are documented as designed
rather than as registered. `/agent/operations.json` carries a `planned` flag that says which is
which; an operation marked `planned` answers 404 today.

Time bars, enforcement flags and deadlines are not settled. The training material, the
conformance specification and the system defaults currently disagree, so
[Not yet settled](/rail/reference/Time-Limits) sets them out as an open conflict rather than as
guidance. Keep those values in configuration rather than in a condition.

Coded lists come from the terminology service. Fetch them; do not paste them into your source.
[Value sets and code systems](/rail/reference/Value-Sets) explains how, and how to cache one
safely.

---

## /onboarding/README

# Onboarding screenshots

Drop the self-onboarding screenshots here using these exact filenames so they
render in the [Self Onboard on eTIMS](../../pages/docs/eTIMS/How-To-Guides/Self-Onboard-on-eTIMS.mdx)
guide:

| Filename | Screen |
|----------|--------|
| `01-welcome.png` | Welcome page (Sign In / Get Started) |
| `02-select-account-type.png` | Select account type (Individual / Business) |
| `03-verify-admin-id.png` | Step 1 of 3 — Verify Admin ID |
| `04-setup-business.png` | Step 2 of 3 — Setup Business |
| `05-activate-business.png` | Step 3 of 3 — Activate Business |

They are referenced in MDX as `/onboarding/<filename>` (Zudoku serves `public/`
at the site root).

---

## /rail/concepts/Integrator-View

# The integrator's view

  Every call on this rail is made while one person stands in front of another, waiting.

## Why this page exists

Endpoint documentation tells you what a payload contains. It does not tell you which screen
the payload fills, who is waiting on it, or what happens to that person when it fails.

That is what this page covers. Everything below runs in three lanes: the desk, which is what
a person sees; your system, which is what you render and call; and the rail, which answers.

The screens below are low fidelity on purpose. They are an argument about what has to be on
screen at each moment, and which field puts it there, not a UI to copy.

## The shape of a visit

Start with the shape, before any screens. A visit behaves less like a form submission and
more like a conversation with pauses in it, and the pauses are where integrations get
designed badly.

<Mermaid chart={`sequenceDiagram
    autonumber
    participant D as Front desk
    participant S as Your system
    participant R as The rail
    D->>S: Patient presents an ID
    S->>R: Resolve identity, with consent
    R-->>S: unique_patient_id + masked contacts
    S->>R: List covers
    R-->>S: Every usable cover
    D->>S: Operator picks a cover
    S->>R: Select cover
    R-->>S: selection_ref
    S->>R: Read the benefit tree
    R-->>S: billable items
    S->>R: Ask for an authentication
    R-->>S: A URL to embed
    S->>D: Render consent (member proves presence)
    R-->>S: authentication id
    S->>R: Open the visit
    R-->>S: visit_id
`} />

Note what the desk does and does not do. It presents an identifier and it picks a cover.
Everything else is your system and the rail talking. If your design has the operator making
decisions at any other point, you have moved work onto a person who does not want it.

## Screen 1 · The front desk

The first screen has one job, which is to turn a human being into an identifier. It usually
fails because the identifier type was never captured alongside the value.

<Wireframe
  title="Find patient"
  actor="Front desk"
  rows={[
    [
      { label: "Identifier type", kind: "field", span: 1, from: "GET /concepts/?system=IDENTIFIER-TYPES", note: "A picker, never free text. One code system on the terminology service." },
      { label: "Identifier value", kind: "field", span: 2, note: "Scanned or typed" },
      { label: "Find", kind: "action", span: 1 },
    ],
    [
      { label: "Patient", kind: "text", span: 2, from: "biodata.name, dob, gender", note: "Enough to confirm the right human" },
      { label: "Consent taken", kind: "text", span: 2, from: "consent.receipt", note: "Evidence, not decoration. Keep it." },
    ],
    [
      { label: "Contact channels", kind: "text", span: 4, from: "contacts.phones[].verified", note: "Masked. Only verified channels can receive a code later." },
    ],
  ]}
  caption={<>The identifier is always a pair. A field for the value with no field for the type is the commonest cause of a false "patient not found".</>}
/>

When this screen fails, a conflict is not an error to retry. It means the identifier matched
more than one person, so the screen should ask for a second identifier instead of showing a
red box. Design that path, because you will use it.

## Screen 2 · Choosing a cover

This is the screen where benefit coordination becomes real. A member with several covers
needs a person to choose between them, and that person needs enough to choose *with*.

<Wireframe
  title="Select cover for this visit"
  actor="Front desk"
  rows={[
    [
      { label: "Patient", kind: "text", span: 4, from: "unique_patient_id", note: "Carried from the previous screen, never re-resolved" },
    ],
    [
      { label: "Covers", kind: "list", span: 4, from: "covers[]", note: "Payer · member number · policy window · status. Already filtered to what is usable here." },
    ],
    [
      { label: "Scheme", kind: "field", span: 2, from: "covers[].schemes[]", note: "Only where a cover runs on several. Hidden otherwise." },
      { label: "Why this cover?", kind: "text", span: 1, note: "Optional, but it is what an audit asks" },
      { label: "Use this cover", kind: "action", span: 1 },
    ],
  ]}
  caption={<>Silently auto-selecting is the tempting shortcut here. Resist it. This is a financial decision, and nobody can audit a choice they could not see being made.</>}
/>

  Some covers run on more than one scheme at once. Render schemes as covers so the operator
  makes one selection instead of two, and so the screen looks the same whichever payer is
  behind it.

## Screen 3 · Consent

This is the screen you mostly do not build. Which proofs are legal at that moment is
resolved from the member, the facility, the payer and the benefit, so what you render is
whatever the rail returns, in a frame.

<Wireframe
  title="Confirm the member is present"
  actor="Member, at the desk"
  rows={[
    [
      { label: "Embedded consent", kind: "list", span: 4, from: "embed_url", note: "The permitted factors appear here. You do not choose them, and should not try to." },
    ],
    [
      { label: "Session expires", kind: "text", span: 2, from: "expires_at", note: "Show it. A front desk gets interrupted." },
      { label: "Start again", kind: "action", span: 2, note: "Reject the stale session first, then open a new one" },
    ],
  ]}
  caption={<>Roughly three adults in ten fail biometric matching, so the fallback is a main path rather than an edge case. Build the recovery screens with the same care as the happy one, because you will see them more often.</>}
/>

## Screen 4 · Billing

Your billers live in this screen. Two things belong on it that are routinely left off: the
lines that are *waiting*, and the cover being billed against.

<Wireframe
  title="Visit billing"
  actor="Biller"
  rows={[
    [
      { label: "Billing against", kind: "text", span: 3, from: "cover + visit_id", note: "Persistent. A biller who cannot see the cover will bill the wrong one." },
      { label: "Add item", kind: "action", span: 1 },
    ],
    [
      { label: "Lines", kind: "list", span: 4, from: "lines[].status", note: "active · held (awaiting approval) · retired. Held lines must be visible, or they get added twice." },
    ],
    [
      { label: "Documents", kind: "text", span: 2, from: "requiredDocuments", note: "Checklist from the item, ticked as attached" },
      { label: "Readiness", kind: "text", span: 1, from: "preflight.reasons[]", note: "Live, not at the end" },
      { label: "Close visit", kind: "action", span: 1, note: "Consent again, because discharge is its own event" },
    ],
  ]}
  caption={<>The readiness panel is worth more than anything else on this screen. Every check pre-flight will run is available while billing, so a claim should never surprise anyone at submission.</>}
/>

## The pauses, and how to design for them

Three moments in the journey are asynchronous. Each needs a state in your system, not a
spinner.

<Mermaid chart={`stateDiagram-v2
    [*] --> Billing
    Billing --> AwaitingApproval: item needs preauthorisation
    AwaitingApproval --> Billing: approved (per item, possibly partial)
    AwaitingApproval --> Returned: sent back for correction
    Returned --> AwaitingApproval: resubmit, same reference
    Billing --> Submitted: pre-flight clean, visit closed
    Submitted --> Returned2: returned for correction
    Returned2 --> Submitted: resubmit, same external_id
    Submitted --> Decided: approved / partially approved / rejected
    Decided --> Paid: remittance matched to invoice
    Paid --> [*]
`} />

Awaiting approval is a state you persist. Honour the polling interval, and let a callback
settle it if one arrives first. A user should be able to close the browser.

Returned is not a rejection but a request that is waiting on you. A returned item that
nobody resubmits is the second commonest reason money never arrives.

Awaiting payment is the gap between approved and paid. Model it explicitly, or your finance
team will build a spreadsheet to do it for you.

## What the desk should never be asked

A short list, all of it learned the expensive way:

<CostTable
  rows={[
    { where: "Identity", symptom: "\"Which ID type is this?\"", cause: "The type should come from the scan or the picker, not from the operator's judgement." },
    { where: "Identity", symptom: "\"Whose licence is on this line?\"", cause: "The clinician is an identity too, resolved by regulator plus registration number. Picked from a typed list, it is only a name with nothing behind it." },
    { where: "Consent", symptom: "\"Should we use fingerprint or a code?\"", cause: "The permitted factors are resolved for you. Offering a choice invents one that may not be legal." },
    { where: "Billing", symptom: "\"Is this covered?\"", cause: "Items were filtered to what is billable at eligibility. If it is on screen it is billable; if it is not, say why." },
    { where: "Submission", symptom: "\"Why was this rejected?\"", cause: "Every reason carries a fix_stage. Route them to the screen that fixes it instead of showing the message." },
  ]}
/>

**Next:** [Ride the rail](/rail/stops/Authenticate) · or read
[benefit coordination](/rail/why/Benefit-Coordination)

---

## /rail/concepts/Next-Action

# The next_action contract

  The client reads its next move out of the response instead of guessing it.

## What it is

Every response from the rail carries a `next_action` object. Its `type` names the move; where
a call is required, `endpoint` carries the fully formed URL to make it against.

```json
{
  "next_action": {
    "type": "check_eligibility",
    "endpoint": "/api/v2/patients/SIL-UPI-0091774/eligibility/SEL-2026-08-14-0091/benefits"
  }
}
```

Take the endpoint from the response. Do not construct it. What comes back already has the
identifiers interpolated, so you get `/api/v2/patients/SIL-UPI-0091774/covers` rather than a
template you have to fill.

## Why it exists

There are two reasons, and the second is the one that bites in production.

The first is that it keeps payer branching out of your client. Payers differ on whether a
preauthorisation is needed, on whether a reservation must be created explicitly or is made
for you, and on whether doctor sign-off is routed elsewhere first. Those differences reach
you as different `next_action` values, so you do not keep a code path per payer.

The second is that it handles legitimate skips. Hard-coding the sequence works until a step
is correctly skipped: an authorisation already granted and still valid, a reservation
auto-created on approval, a preauth that turned out not to be required. A client that walks
a fixed list either repeats work or stalls. Reading `next_action` avoids both, and it takes
no conditionals on your side.

## The full enum

<Wire
  rows={[
    { call: "select_cover", does: "Render the cover chooser and call cover selection", keep: "endpoint" },
    { call: "check_eligibility", does: "A cover was selected, so check eligibility against it", keep: "endpoint" },
    { call: "select_benefit", does: "Show the benefit or item picker, fresh or because the previous choice is now blocked", keep: "endpoint" },
    { call: "assign_location", does: "A service location must be set before anything else proceeds", keep: "—" },
    { call: "authenticate", does: "Offer the consent factors listed in available_factors", keep: "available_factors" },
    { call: "submit_challenge", does: "A one-time code was dispatched, so collect and submit it", keep: "endpoint, expires_at" },
    { call: "submit_preauth", does: "Authorisation granted and an item needs preauthorisation", keep: "endpoint" },
    { call: "manual_confirmation", does: "Preauth is required but confirmed outside the API, so proceed provisionally", keep: "—" },
    { call: "await_decision", does: "Poll the endpoint, or wait for the registered callback", keep: "endpoint, poll_after_ms" },
    { call: "reserve", does: "An approval needs an explicit reservation call", keep: "endpoint" },
    { call: "fix", does: "Pre-flight found blockers, and reasons[] names each one with a fix_stage", keep: "reasons[]" },
    { call: "submit", does: "Every gate has passed, so close the claim", keep: "endpoint" },
    { call: "none", does: "Nothing further is required right now", keep: "—" },
  ]}
/>

## How to build against it

<BuildSequence
  steps={[
    "Model next_action.type as an enum in your own code, with an explicit unknown case. New values can be added; an unknown value should surface as 'unhandled step' rather than crashing or silently stopping.",
    "Write one dispatcher that switches on the type. Every screen in your flow is reached from it. Resist adding a second path 'just for this case'.",
    "Always take endpoint from the response. If your code contains a string-concatenated rail URL, it will break the next time a payer changes something.",
    "Treat await_decision as a state, not a wait. Persist it, honour poll_after_ms, and let the callback settle it if one arrives first.",
    "Treat none as terminal for the current step, not for the flow. It means nothing more is needed here, and your own workflow decides what happens next.",
    "Log the type on every transition. When a flow stalls in production, the sequence of next_action values tells you where it stopped.",
  ]}
/>

## The common mix-up

`none` and `await_decision` look similar from a UI perspective, because in both cases nothing
is required of the operator right now. They are not the same.

`none` means the rail has nothing further for you at this point. `await_decision` means a
decision is outstanding somewhere else and will arrive, and that you are expected to be
listening. Treat the second as the first and a preauth approval can sit unnoticed for a
day.

## Errors carry their own routing

Failures use the same discipline. Every error carries `error`, `message`, `path` and
`fix_stage`. Validation returns every reason at once rather than one at a time, so a
correction takes one round rather than a queue of them.

`fix_stage` tells you where in the sequence the correction belongs. Combined with
`next_action.type: "fix"` and the `reasons[]` array at pre-flight, you can route an operator
straight to the screen that can resolve the problem instead of asking them to hunt.

**Next:** see it drive a real sequence on the [golden path](/rail/stops/Identify).

---

## /rail/concepts/Onboarding

# Onboarding onto Advantage

> No stop on the rail is callable until an account exists, and an account only exists once a
> register has confirmed it.

Every page after this one assumes you already hold a credential. This page covers how one is issued.

Self-service onboarding is a public, unauthenticated funnel. A registrant arrives at the welcome
landing with no token and leaves with an activated account they can sign in to. Identity is never
self-asserted anywhere in it. The registrant supplies an identifier, the rail retrieves the official
record behind it, and the verification code goes to the email address on that record rather than to
one the registrant types. By the time the account exists, whoever holds it has shown they can read
mail at an address a licensing body published.

Two tracks run off the same funnel. An individual, meaning a solo practitioner, verifies one
identity and activates. A business, meaning a clinic or facility with one location or many, verifies
the admin, then the facility, then activates. Both are the same four moves: look up, confirm, enter
the code, continue.

<Mermaid chart={`flowchart TD
  W["Welcome landing<br/>Get Started"] --> T{"Account type"}
  T -->|Individual| A["01 · Verify admin identity"]
  T -->|Business| A
  A --> AR["Registry search"]
  AR --> AC["Confirm details"]
  AC --> AO["Code to the registered email"]
  AO -->|Individual| Z["03 · Activate account"]
  AO -->|Business| B["02 · Setup business"]
  B --> BR["Facility registry search"]
  BR --> BC["Confirm business details"]
  BC --> BO["Code to the facility email"]
  BO --> Z
  Z --> ZE["Check your email<br/>temporary password"]
  ZE --> ZS["Sign in · set a new password"]
  ZS --> ZD["Account activated"]
  ZD -.->|"no subscription"| P["Plan · billing · M-Pesa"]
  ZD --> R["00 · Authenticate on the rail"]
  P --> R
  A -.->|"registry has nothing"| M["Enter details manually"]
  M --> Z
  AC -.->|"cannot open that inbox"| E["Manual verification<br/>1 to 2 business days"]
`} />

<Mermaid chart={`sequenceDiagram
    autonumber
    actor U as Registrant
    participant F as Advantage
    participant O as Onboarding API
    participant X as Registries (KMPDC, BRS, KRA)
    participant M as Their inbox

    U->>F: Identifier type + number
    F->>O: registry-search
    O->>X: Look up the official record
    X-->>O: Name, licence, status, email
    O-->>F: registry_result_id + details
    F-->>U: Confirm these details
    U->>F: Confirm
    F->>O: send-verification
    O->>M: 6-digit code to the registry's email
    U->>F: Code
    F->>O: verify-code
    O-->>F: verification_token
    F->>O: complete-registration
    O->>M: "Welcome - Your Temporary Password"
    U->>F: Sign in, set a new password
    Note over U,F: The account exists and can now hold credentials.
`} />

<Mermaid chart={`flowchart LR
  A["Identifier + type"] -->|"registry_result_id"| B["Confirmed record"]
  B -->|"the registry's email"| C["Code sent"]
  C -->|"verification_token"| D["Registration completed"]
  D -->|"temporary password"| E["First sign-in"]
  E -->|"a real password"| F["An account"]
  F -->|"client credentials"| G["00 · Authenticate"]
`} />

## The map

| # | Step | The question it answers | What the registrant leaves with |
|---|------|------------------------|-------------------------------|
| 0 | **Account type** | Solo practitioner, or a business with locations? | the track, and whether it runs two steps or three |
| 1 | **Verify admin identity** | Who is setting this up, and are they licensed to? | `registry_result_id` and `verification_token` |
| 2 | **Setup business** *(business only)* | Which facility is this, and is its registration current? | the facility's confirmed record |
| 3 | **Activate account** | Can they read mail at the address the registry holds? | a temporary password, then a real one |
| | **Plan and billing** *(where required)* | Is there an active subscription behind this org? | a receipt, and the app unlocked |

The step count is the only difference between the tracks. Individual runs two steps, verify then
activate. Business runs three, verify the admin, set up the business, then activate. The stepper at
the top of the screen is built from that choice.

## Step 0 · Which account is being set up

<Wireframe
  title="Let's get you set up!"
  actor="Registrant · not signed in"
  rows={[
    [
      { label: "Who are you setting this up for?", kind: "text", span: 4, note: "You can change this later if needed" },
    ],
    [
      { label: "Individual", kind: "field", swatch: 1, span: 2, note: "Solo practitioners and independent health or wellness professionals. Two steps." },
      { label: "Business", kind: "field", swatch: 2, span: 2, note: "Clinics, facilities, or businesses operating one or more locations. Three steps." },
    ],
    [
      { label: "Back", kind: "action", span: 1 },
      { label: "Continue", kind: "action", span: 3 },
    ],
  ]}
  caption={<>A deployment that only registers one kind of account skips this screen and carries its pinned type into the funnel, so the registrant is never offered a choice that does not apply to them.</>}
/>

The choice travels as a route parameter for the rest of the funnel, so it survives a refresh or a
back-navigation. It is also the last thing the registrant asserts on their own. Everything after it
is checked against a register.

## Step 1 · Verify the admin identity

Whoever sets up an account may be an admin, the owner, or a staff member assigned to do it, and is
not always the person the account is about. This step establishes who is at the keyboard and whether
a licensing body knows them.

It opens on a choice of identifier, and that choice decides how much typing follows.

<Wireframe
  title="Verify your professional registration"
  actor="Registrant · step 1 of 2 or 3"
  rows={[
    [
      { label: "I'm registered with KMPDC", kind: "field", swatch: 1, span: 2, note: "Doctors, dentists, clinical officers. We retrieve the details automatically." },
      { label: "Other professional registration", kind: "field", swatch: 2, span: 2, note: "Nurses, therapists, public health. Details entered by hand, about 3 minutes." },
    ],
    [
      { label: "Identifier number", kind: "field", span: 3, from: "identifier.number", note: "Exactly as it appears on the official record, for example A1234" },
      { label: "Can't find it?", kind: "action", span: 1, note: "Leads to the manual form" },
    ],
    [
      { label: "I confirm compliance with the Data Protection Act and that patient consent is obtained before sharing health records", kind: "text", span: 4, note: "The button stays disabled until this is ticked" },
    ],
    [
      { label: "Back", kind: "action", span: 1 },
      { label: "Continue, then Checking registry", kind: "action", span: 3, from: "POST registry-search" },
    ],
  ]}
  caption={<>Nothing is saved at this point. The identifier only retrieves a record, and the registrant reviews it before anything is written, which is what the screen says.</>}
/>

A hit comes back as a complete professional record, so the next screen reviews it instead of asking
for it. The fields are read only, and the screen says where to go when something is wrong: the
licensing body holds the record and Advantage only displays it. A copy anyone could edit would prove
nothing.

<Wireframe
  title="Confirm your professional details"
  actor="Registrant · retrieved from the registry"
  rows={[
    [
      { label: "Dr Jane Doe", kind: "text", swatch: 1, span: 2, from: "full_name" },
      { label: "Speciality / cadre", kind: "text", swatch: 1, span: 2, from: "speciality_cadre" },
    ],
    [
      { label: "KMPDC", kind: "text", span: 1, from: "licensing_body" },
      { label: "Registration / licence number", kind: "text", span: 1, from: "registration_number" },
      { label: "Licence active", kind: "field", tone: "positive", span: 1, from: "licence_status" },
      { label: "Valid to 31 Dec 2026", kind: "text", span: 1, from: "licence_validity_end_date" },
    ],
    [
      { label: "j****@practice.co.ke", kind: "field", tone: "attention", span: 4, from: "email", note: "To protect your privacy, we'll send a verification code to your registered email address. This one, taken from the record." },
    ],
    [
      { label: "Contact your licensing body to correct anything wrong here", kind: "text", span: 2 },
      { label: "Send code", kind: "action", span: 2, from: "POST send-verification" },
    ],
  ]}
  caption={<>Everything turns on this email. It comes from the registry, it cannot be edited, and the code goes to it, so a licence number on its own gets nobody an account.</>}
/>

The code is six digits, expires in minutes, and can be resent. Verifying it returns a
`verification_token`, and what happens next is the one place the two tracks diverge:

<Wire
  rows={[
    { call: "Individual", does: "The registration completes here. The token is spent immediately and the registrant goes straight to activation.", keep: "an account, pending activation" },
    { call: "Business", does: "The result id and token are held rather than spent, and travel into the business payload later. A business account exists only once the facility behind it is confirmed too.", keep: "registry_result_id and verification_token" },
  ]}
/>

Business admins skip the KMPDC lookup and land straight on the manual admin form. Whoever registers
a clinic is often an administrator with no clinical licence to look up, so asking them for a
practitioner number first would strand them on the first screen.

<Wireframe
  title="Enter admin details"
  actor="Registrant · manual branch"
  rows={[
    [
      { label: "Full name", kind: "field", span: 2, from: "full_name" },
      { label: "Profession", kind: "field", span: 2, from: "profession", note: "Searchable list" },
    ],
    [
      { label: "Work email", kind: "field", span: 2, from: "email", note: "We'll send a verification link to this address" },
      { label: "Phone number", kind: "field", span: 2, from: "phone", note: "A 6-digit code goes here by SMS" },
    ],
    [
      { label: "I am the business owner", kind: "field", span: 4, from: "is_business_owner", note: "The owner is legally responsible for the account. Setting it up on someone's behalf? Leave it unchecked." },
    ],
    [
      { label: "Consent to collection, processing and storage under the Terms & Privacy Policy", kind: "text", span: 3 },
      { label: "Continue", kind: "action", span: 1, from: "POST manual-registration" },
    ],
  ]}
  caption={<>The manual branch serves every profession whose register the rail does not read live. It costs one form, and it produces the same account.</>}
/>

## Step 2 · Setup business

Business only. It repeats step 1 one level up, asking the same four questions about a facility
instead of a person.

<Wire
  rows={[
    { call: "Registered with KMPDC", does: "The facility register is read live. Details come back complete: name, level, ownership, type, licence validity, location.", keep: "the facility's record" },
    { call: "Other business registration", does: "KRA, BRS, county government, or any other permit. The registrant supplies business name, industry, business email, phone, physical and postal address by hand.", keep: "the same record, typed" },
  ]}
/>

The code for this step goes to the facility's registered email, often a reception or practice
manager address rather than the admin's own inbox. That is deliberate. Verifying a person and
verifying the business they claim to represent are two separate checks, and running both through one
inbox would make the second one free.

Completing this step creates the business account. The admin's held `registry_result_id` and
`verification_token` go up alongside the facility's, and both identities are registered in one call.

<Wireframe
  title="Confirm your business details"
  actor="Registrant · step 2 of 3"
  rows={[
    [
      { label: "Nairobi Family Clinic", kind: "text", swatch: 2, span: 2, from: "business_name" },
      { label: "Level 3 · private", kind: "text", swatch: 2, span: 2, from: "facility_level, business_ownership" },
    ],
    [
      { label: "Business ID", kind: "text", span: 1, from: "business_id" },
      { label: "Licensing body", kind: "text", span: 1, from: "licensing_body" },
      { label: "Licence active", kind: "field", tone: "positive", span: 1, from: "licence_status" },
      { label: "Valid to 30 Jun 2027", kind: "text", span: 1, from: "licence_validity_end_date" },
    ],
    [
      { label: "Business location", kind: "text", span: 4, from: "business_location" },
    ],
    [
      { label: "Back", kind: "action", span: 1 },
      { label: "Send code to the business email", kind: "action", span: 3, from: "POST facility/send-verification" },
    ],
  ]}
  caption={<>An expired facility licence is the most common reason a business account cannot be completed. The status line shows it here, minutes into onboarding, instead of at the first claim.</>}
/>

## Step 3 · Activate the account

Registration and activation are deliberately separate. Registration establishes that the identities
check out; activation establishes that a human can read the mailbox they are attached to.

<Wireframe
  title="Check your email"
  actor="Registrant · final step"
  rows={[
    [
      { label: "One more step. We've sent an activation email to j****@practice.co.ke", kind: "text", span: 4 },
    ],
    [
      { label: 'Find the email titled "Welcome - Your Temporary Password"', kind: "text", span: 2, note: "Spam and junk included. This is where most stalls happen." },
      { label: "Copy the temporary password", kind: "text", span: 2 },
    ],
    [
      { label: "Open Gmail", kind: "action", span: 1 },
      { label: "Open Outlook", kind: "action", span: 1 },
      { label: "Open Yahoo", kind: "action", span: 1 },
      { label: "Sign in", kind: "action", span: 1, note: "You'll be asked to create a new password" },
    ],
    [
      { label: "The activation link expires in 24 hours", kind: "field", tone: "attention", span: 4 },
    ],
  ]}
  caption={<>The temporary password is single use: the first sign-in forces a reset. Until that sign-in happens there is a registration on file but no usable account.</>}
/>

After that the account is live and the registrant lands on the dashboard.

## Where the funnel forks

Three branches, each there so a registrant who falls out of the happy path still has a way to finish.

<Wire
  rows={[
    { call: "The registry has nothing", does: "Every lookup screen carries a 'can't find your identifier' link into the manual form. The registrant types what the registry would have supplied.", keep: "the same account, a form later" },
    { call: "The inbox is unreachable", does: "The address on the registry record is stale, or belongs to a former employer. Manual verification is queued instead and reviewed within 1 to 2 business days.", keep: "a pending verification" },
    { call: "A licence needs evidence", does: "The compliance screen takes the regulator and a licence or accreditation upload (PDF, JPG or PNG). Checks run automatically, and a failed automatic check queues a manual review within 48 hours.", keep: "an uploaded licence, verified or queued" },
  ]}
/>

Two behaviours that generate support tickets when nobody knows about them:

<BuildSequence
  steps={[
    { do: "A refresh resumes the step, a restart clears it", detail: <>Progress inside a step is cached: the retrieved record, the view the registrant is on, and the verification token. A reload picks up where it left off. Entering the funnel again clears all of it, so a half finished attempt from last week cannot leak stale details into a new one.</> },
    { do: "Signed-in users are redirected off the funnel", detail: <>Every public onboarding screen sends an authenticated user elsewhere, including on a typed URL or a back-navigation. Somebody who already has an account and wants to attach it to an organisation needs account linking, which is a separate flow.</> },
  ]}
/>

## The calls behind the screens

The funnel is unauthenticated by design. There is no bearer token yet, so the check that carries the
weight is the code sent to the address the registry holds.

<Wire
  rows={[
    { call: "POST /api/v1/onboarding/individual/registry-search", does: "Look up a professional by identifier type and number.", keep: "registry_result_id and the record" },
    { call: "POST /api/v1/onboarding/individual/send-verification", does: "Send a 6-digit code to the email on the retrieved record.", keep: "nothing" },
    { call: "POST /api/v1/onboarding/individual/verify-code", does: "Exchange the code for a token proving the address was read.", keep: "verification_token" },
    { call: "POST /api/v1/onboarding/individual/complete-registration", does: "Create the account from the confirmed record and token.", keep: "an account, pending activation" },
    { call: "POST /api/v1/onboarding/individual/manual-registration", does: "The same, from details typed by hand when no register answers.", keep: "an account, pending activation" },
    { call: "POST /api/v1/onboarding/business/facility/registry-search", does: "The facility equivalent of the first call.", keep: "registry_result_id and the facility record" },
    { call: "POST /api/v1/onboarding/business/facility/send-verification · verify-code", does: "Code to the facility's registered email, then the exchange.", keep: "the facility's verification_token" },
    { call: "POST /api/v1/onboarding/business/admin/validate", does: "Check the admin identity against the facility being registered before the two are joined.", keep: "a validated admin" },
    { call: "POST /api/v1/onboarding/business/complete-registration", does: "Register admin and facility together, both tokens in one payload.", keep: "a business account" },
  ]}
/>

## After activation, before the rail

One gate can still sit between an activated account and the app. Where the organisation needs a
subscription, the first navigation into any authenticated screen is intercepted and sent to plan
selection: a plan, then billing, then an M-Pesa STK push confirmed on the phone, then a receipt. It
runs as a hook on the router, so it fires however the user arrived, whether straight out of
onboarding or from a bookmark six weeks later.

Past that the account holds credentials, which is where the rest of this documentation starts.

  The account exists, so now get your system onto the rail. Client credentials, the facility your
  token is scoped to, and the token every later call carries.

  Invoicing through the revenue branch needs a separate registration against KRA, done once and
  independently of this one.

---

## /rail/concepts/The-Eight-Steps

# The rail, end to end

  Cover in this country sits in two worlds, the national public payer and the private payers, and a
  patient can belong to both on the same day. The rail is one connection that reaches both.

## What the rail is

Behind a patient there may be the national public payer, a private insurer, an employer fund, or several
at once. Each of those has its own membership register, its own benefit rules, its own tariffs and
its own claim format. Reaching them yourself means an integration per payer, and a new one every
time a payer changes something.

The rail sits in the middle of that. You connect to it; it connects to them.

<Wire
  rows={[
    { call: "One connection, both worlds", does: "The national public payer and the private payers answer through the same calls, in the same shapes. Which of them is behind a given member stops being your problem, and stops being a branch in your code.", keep: "one integration" },
    { call: "The national registries, included", does: "Patient identity, practitioner licensing, facility records and the coded vocabularies everything is expressed in. You read them through the rail rather than integrating with each.", keep: "resolved identities" },
    { call: "The hard parts, absorbed", does: "Which fund pays, which tariff applies at your facility, whose balance is read, what needs approving, how a claim is assessed, how overlapping covers coordinate. All of it happens behind the calls you make.", keep: "your part stays small" },
  ]}
/>

Most of the work sits in the third row. At every stop the pattern is the same: you supply a
decision a human made, and the rail resolves everything that follows from it. You send the
identifier a patient handed over, the cover an operator chose, the clinician who treated them and
the items that were done. You do not rank payers, split funds, price against a contract or compute
what is left on a limit.

## What end to end means

One patient, from walking through the door to the facility's reimbursement landing in its bank
account, is ten labelled stops. Only nine of them are about the patient. `00` is how your
system gets onto the line in the first place, and it happens once at start-up rather than per visit.

| # | Stop | The question it answers | What you keep |
|---|------|------------------------|---------------|
| 00 | Authenticate | Who is asking, and from which facility? | an access token, and the facility headers |
| 01 | Identify | Who is being treated, who is treating them, and where? | `unique_patient_id`, plus the clinician's registration |
| 02 | Verify cover | Which cover pays, and what does it pay for here today? | `selection_ref`, and the billable units read against it |
| 03 | Consent | Can we prove they were present and willing? | an authorisation reference |
| 04 | Visit | Is the encounter open, and against which cover? | `visit_id` |
| 05 | Treat | What was found, what was done, and who else needs to know? | `diagnosis_id`, and a record written to the SHR |
| 06 | Preauthorize | Does this need approving before it may be done? | an approval reference and per-item approved amounts |
| 07 | Bill | What was actually done, and what does it price at? | line references, reservations |
| 08 | Submit | Is the claim complete enough to send? | `claim_id` |
| 09 | Reconcile | Did the money arrive, and against what? | a remittance matched to an invoice |

Every scenario you will meet is this sequence with different values in it. An outpatient visit, an
admission, an emergency, a dependant on somebody else's cover and a member with four active
schemes all run in the same order, with different answers. Once you know the order, each new case is a
variation on it rather than something to work out from scratch.

## What success looks like

Calling all ten stops does not make an integration finished. It is finished when the things below
are true, because each of them is a job that otherwise lands on a person every single day.

<BuildSequence
  steps={[
    {
      do: "No coded value is typed by hand",
      detail:
        "Every picker (identifier types, diagnoses, interventions/services, document types) is fetched from the terminology service in the right versions. Nothing is transcribed into a constant.",
    },
    {
      do: "A patient is resolved from what they handed over",
      detail:
        "An identifier and its type, including the cases that are harder than a card: dependants, minors, a member whose document does not match the register. One resolved identity carried forward.",
    },
    {
      do: "The cover is chosen by a person, and visibly",
      detail:
        "Every cover the member can use here is listed, somebody selects one, and the choice is recorded and changeable until the claim is submitted. The system never picks one on its own.",
    },
    {
      do: "Consent is proof, not a checkbox",
      detail:
        "Whatever modality the payer requires (a one-time code, biometrics, a guardian), it is collected through one flow and produces a reference the claim can carry.",
    },
    {
      do: "The price is yours, and it is checked while the patient is still there",
      detail:
        "The facility sets what it charges. Where a payer states a tariff for that item, the rail validates the line against it as the line is added, so a rate problem surfaces at the desk rather than as a rejection weeks later, when the patient has gone home and the correction costs a person instead of a keystroke.",
    },
    {
      do: "Claims and preauthorisations fail at entry, not at submission",
      detail:
        "Of everything here, this is the one worth building for. Your system catches what is wrong while the encounter is open, whether that is a missing document, an unmapped code, a benefit that does not cover this access point or a diagnosis the procedure does not support, and it says what is wrong and what would fix it. Every one of those caught at the desk is a rejection that never happens, and a correction that costs seconds rather than a follow-up.",
    },
    {
      do: "Decisions arrive without being chased",
      detail:
        "Preauthorisation and claim outcomes are delivered to a registered callback. Nobody polls or refreshes a screen waiting for an answer.",
    },
    {
      do: "Remittances match themselves",
      detail:
        "Payments land against the invoices they belong to automatically, and only the exceptions reach a human, as a short worklist rather than a reconciliation exercise.",
    },
  ]}
/>

If you want a single test: in a fully integrated system nobody's job is to re-enter, chase or
reconcile anything the rail already knows, and almost nothing reaches submission that the desk
could have caught.

The second half is what the errors are shaped for. Every error the rail returns names the stage that
can resolve it, so your interface can route a problem to the screen that fixes it instead of
reporting it where it was noticed. See [the error dictionary](/rail/reference/Errors).

## Three ways to read the sequence

Where the stops sit on the line, who talks to whom while a visit runs, and what each step hands the
next.

<Mermaid chart={`sequenceDiagram
    autonumber
    actor D as Front desk
    participant H as Your HMIS
    participant R as The rail
    participant X as Registries & payers

    H->>R: Credentials + facility
    R-->>H: Token
    D->>H: Identifier pair
    H->>R: Resolve the patient
    R->>X: Client registry
    X-->>R: One identity
    R-->>H: unique_patient_id
    H->>R: Covers for this member here
    R->>X: Coverage and contributions
    X-->>R: One entry per scheme per contributor
    R-->>H: Covers to choose from
    D->>H: Chooses a cover
    H->>R: Freeze it, then open the visit
    R-->>H: visit_id
    H->>R: The coded diagnosis, and the encounter
    R->>X: Shared health record
    H->>R: Bill the items that were done
    R-->>H: Priced lines
    H->>R: Submit the claim
    R->>X: Assessment
    X-->>R: Decision, later
    R-->>H: Callback, then remittance
    Note over H,R: Your side is decisions and items.<br/>Everything crossing to the right is absorbed.
`} />

<Mermaid chart={`flowchart TD
  A["00 · Authenticate"] -->|"token + facility"| B["01 · Identify"]
  B -->|"unique_patient_id"| C["02 · Verify cover"]
  C -->|"the chosen cover"| D["03 · Consent"]
  D -->|"an authorisation"| E["04 · Visit"]
  E -->|"visit_id"| T["05 · Treat"]
  T -->|"coded diagnosis, linked"| F["06 · Preauthorize"]
  T -.->|"the encounter, as FHIR"| S["Shared health record"]
  F -->|"approval + amounts"| G["07 · Bill"]
  G -->|"priced lines"| H["08 · Submit"]
  H -->|"claim_id"| I["09 · Reconcile"]
  G -.->|"invoice, not a claim"| J["eTIMS branch"]
`} />

If you find yourself holding a value and not knowing what it is for, it is almost always the
input to the step after the one you are on.

## Step 1 is three identities, not one

Almost every integration reads "Identify" as "look the patient up", builds that, and meets the
other two identities months later as claim rejections. A billable encounter eventually has to
assert three things, so it is cheaper to know that on day one.

<Wire
  rows={[
    { call: "The patient", does: "Who is being treated. Start here, because nothing else on the rail can begin until this resolves, and every later step takes it as input.", keep: "unique_patient_id" },
    { call: "The healthcare worker", does: "Who is treating them, and whether their licence permits it. Resolved when the clinician is chosen, re-checked at preauthorisation and billing.", keep: "registration number + regulator" },
    { call: "The facility", does: "Where this is happening. Already carried by your credential, and it scopes the rules, price included.", keep: "facility_code" },
  ]}
/>

The patient is the one to build first, and the only one that gates everything. The other
two are cheap to add early and expensive to add late. A clinician whose licence lapsed produces
a rejected claim days after the care was given, by which time the encounter is closed and the
patient has gone home.

All three resolve the same way, an identifier plus what kind of identifier it is, so the second
and third cost you a form each rather than a new mental model.
[01 · Identify](/rail/stops/Identify) covers all three.

## The clearest example of the division

A member may hold covers from several payers, be a dependant on some of them, and have overlapping
benefits across them. Working out how those interact is the rail's side of the line. Your part is to
list them, let somebody choose, and send that choice back.

## Why the order is the order

The sequence is not administrative preference. Each step is a precondition for the next,
and skipping one does not fail where you skipped it. It fails later, looking like a different problem.

Identify comes before eligibility because coverage is answered per person and per scheme, and
you cannot ask about cover you have not established exists.

Eligibility comes before consent because what you are asking the member to consent to depends on
what is being accessed.

Consent comes before the visit because the visit is bookended by authorisation. Opening an
encounter is a consent event in its own right.

The visit comes before billing because a line has to attach to something. Pricing is resolved live
against the cover frozen onto the visit.

Billing comes before submission because submission runs every completeness gate again, and a claim
assembled after the fact is assembled from memory.

Submission comes before reconciliation because payment matches on the invoice reference, not on the
member, the amount, or the date.

## The two reorderings

Elective care moves preauthorisation ahead of the visit. Approval is sought before the
patient arrives; the visit then opens against an approval that already exists.

Emergency care reverses the first two steps. Treatment begins before identity is
established, and identity is attached afterwards, with the claim carrying the correction.

Everything else about the spine holds in both cases.

## Where you are, always

Readers arrive in the middle, from a search result, a colleague's link or an agent's
citation, so every page in this section shows the spine with the current step lit. If you
have landed somewhere unfamiliar, the strip at the top of the page tells you what came
before it and what comes after.

## What drives the sequence at runtime

You do not hard-code the order. Every response carries `next_action`, naming the move and,
where relevant, the endpoint to call. Your client switches on that enum.

Hard-coding the sequence works right up until a step is legitimately skipped: an
already-granted authorisation, an auto-created reservation, a preauth that was not
required. Then it stops working. Reading `next_action` handles those cases without
you writing a single branch.

See [`next_action`: the contract](/rail/concepts/Next-Action) for the full enum.

**Next:** walk it end to end, starting at [Authenticate](/rail/stops/Authenticate).

---

## /rail/guides/Beneficiary-Lookup

# Dependants and the hard cases

  One adult with one card is the happy path, and no front desk needs help with it. The hard
  cases are the child with no document of their own, the patient who arrives unconscious, and
  the registry that will not answer.

Read [01 · Identify](/rail/stops/Identify) first. That page covers the step itself, meaning what
a lookup is, the identifier pair, the four moves, the three identities and what breaks. This
page only picks up what that one leaves out.

  Field names here are illustrative and still under review. Read them for the shape of the work,
  which is what you resolve and in what order. Take the exact names from
  [the Rail API reference](/rail-api/01-identify) once the contracts are signed off.

## Identifying a dependant

This is the case that catches integrations out, because a dependant often has nothing to type
into an ID field. There are two routes to them, and you need both.

<Mermaid chart={`flowchart TD
    A["A child or spouse is at the desk"] --> B{Do they have a usable identifier?}
    B -- Yes --> C["Look them up directly<br/>BIRTH_CERTIFICATE / BIRTH_NOTIFICATION / NATIONAL_ID"]
    C --> D["Resolved, on their own registry identifier"]
    B -- No --> E["Look up the PRINCIPAL instead"]
    E --> F["Read dependants[], grouped by relationship"]
    F --> G["Operator picks the dependant"]
    G --> H["Use that dependant's identifier from here on"]
    E --> I["unconfirmed_dependants[], declared but not verified"]
    I --> J["Flag for verification.<br/>Do not quietly treat as covered"]
`} />

The first route uses the dependant's own identifier. A child with a birth certificate or a
birth notification is an ordinary lookup with nothing special about it, because the type field
carries the difference.

The second route goes through the principal. Look the principal up, read `dependants[]`, and
let the operator choose. Each group carries a `relationship` and a `total`, so the screen can
render *Children (2)* and *Spouse (1)* instead of one flat list.

`unconfirmed_dependants[]` is a different thing. These have been declared but not yet verified
by the registry, and `related_to` points back at the principal. Some are legitimately pending.
They are also where fraud surfaces first. Render them separately, label them, and let the cover
check decide payability.

<Wireframe
  title="Dependants of Miriam T***"
  actor="Front desk"
  rows={[
    [
      { label: "Principal", kind: "text", span: 4, from: "principal identifier + name", note: "Always visible, because the operator needs to know whose cover this is." },
    ],
    [
      { label: "Children (2)", kind: "list", span: 4, from: "dependants[].result[]", note: "Name · date of birth · relationship · Select" },
    ],
    [
      { label: "Spouse (1)", kind: "list", span: 4, from: "dependants[].result[]" },
    ],
    [
      { label: "Declared, not yet verified (1)", kind: "field", tone: "attention", span: 4, from: "unconfirmed_dependants[]", note: "Separated and labelled on screen. Selectable, but not assumed to be covered." },
    ],
  ]}
  caption={<>Put confirmed and unconfirmed dependants in one undifferentiated list and an unverified dependant will end up billed as a covered one.</>}
/>

  Carry the principal onto the screen and onto the record. Every audit conversation about a
  dependant's claim opens with "under whose cover?", and that answer should be stored at the
  time rather than reconstructed months later.

Once resolved, a dependant is just a patient with their own identifier, carried forward like
anyone else's. The relationship matters for cover, which is
[02 · Verify cover](/rail/stops/Entitle), but it makes no difference to identity.

## The situations a front desk meets

There are six. In each one the mistake is resolving too late, resolving too often, or resolving
with too little to go on.

<CostTable
  rows={[
    {
      where: "Reception, new patient",
      symptom: "Someone presents for the first time at your facility",
      cause:
        "Look them up before you open a local file. Create the record first and resolve later, and you end up with two records for one person and no clean way to merge them.",
    },
    {
      where: "Reception, returning patient",
      symptom: "Someone you have seen before comes back",
      cause:
        "Do not re-resolve them by national ID. You stored the registry identifier the first time, so use it. This is the biggest single saving available at a busy desk.",
    },
    {
      where: "Reception, a child or spouse",
      symptom: "A dependant is presenting, often with no document of their own",
      cause:
        "Look up the person whose cover it is, then pick the dependant from their record, as above.",
    },
    {
      where: "Triage or casualty",
      symptom: "An unconscious or unidentified patient arrives",
      cause:
        "Treat first. Identity resolves on a temporary registration and is reconciled afterwards, so the lookup never blocks care.",
    },
    {
      where: "Admission",
      symptom: "An inpatient is being admitted",
      cause:
        "The identity must already be resolved. An admission opened against an unresolved patient produces a claim nobody can attach to a person.",
    },
    {
      where: "Cashier or pharmacy",
      symptom: "A bill or a dispense is being raised",
      cause:
        "Do not look up again. Carry the identifier forward from the desk. Re-resolve mid-encounter and the same patient ends up billed under two identities.",
    },
  ]}
/>

The rule underneath all six is to resolve once per patient, as early as you can, and then carry
the result.

## When the registry is slow

The registry is a national system reached over a network, and sometimes it answers more slowly
than a person standing at a desk is willing to wait. Design for that rather than treating it as
an incident.

<BuildSequence
  steps={[
    {
      do: "Choose your own timeout",
      detail:
        "Three to five seconds, set by you rather than whatever your HTTP library defaults to, which is usually far too long for someone standing at a counter.",
    },
    {
      do: "Retry once, idempotently",
      detail:
        "Reuse the same lookup reference so the attempt is de-duplicated upstream rather than recorded twice.",
    },
    {
      do: "Cap the total wait",
      detail:
        "Once you are past your budget, stop calling and change the screen. Telling the operator you will follow up beats holding them on a spinner that never ends.",
    },
    {
      do: "Offer a pending path",
      detail:
        "Let the desk carry on. Take the details, open the encounter on a temporary identity, resolve in the background and reconcile when the registry answers.",
    },
    {
      do: "Cache for life, not for a session",
      detail:
        "Most patients are returning patients, so most registry latency never reaches a user. One resolution per patient per lifetime removes most of this problem before any timeout tuning does.",
    },
  ]}
/>

<Wireframe
  title="Find patient, registry not responding"
  actor="Front desk"
  rows={[
    [
      { label: "Checking with the client registry", kind: "text", span: 3, note: "Elapsed time on screen, rather than a spinner with no end." },
      { label: "Continue anyway", kind: "action", span: 1 },
    ],
    [
      { label: "Opens the encounter on a temporary identity", kind: "field", tone: "attention", span: 4, note: "Queues the lookup and reconciles when the registry answers. Audited, and on a report until it does." },
    ],
  ]}
  caption={<>The one thing to avoid is a modal the receptionist cannot dismiss. A queue of people waiting is worse than a deferred identity.</>}
/>

  Track how many are outstanding and how long they have been open. An integration that opens
  them and never reconciles produces claims that cannot be attached to a person. That is the
  same failure as never looking anyone up, only it arrives later and is harder to trace.

## Next

Back to [01 · Identify](/rail/stops/Identify) for the step itself, or on to
[02 · Verify cover](/rail/stops/Entitle), where a resolved identity becomes a question about cover.

<AgentPrompt title="Build the hard cases with an agent" filename="identify-hard-cases.instructions.md">{`You are extending an HMIS integration with the Savannah unified payer rail.

Assumed already built: patient lookup by identifier pair (see 01 · Identify).
Task: handle dependants and the degraded paths.

DEPENDANTS (two routes, implement both):
  1. The dependant holds their own document (BIRTH_CERTIFICATE, BIRTH_NOTIFICATION,
     NATIONAL_ID): an ordinary lookup, nothing special.
  2. They hold nothing: look up the PRINCIPAL, read dependants[] (grouped by
     relationship, each group carrying a total), let the operator select, then use
     that dependant's own registry identifier from there on.
  Render unconfirmed_dependants[] as a separate, labelled group, declared but not
  verified. Selectable, never assumed covered; let the cover check decide.
  Persist the principal against the encounter: "under whose cover?" is the first
  question any audit of a dependant's claim asks.

FRONT-DESK RULES:
  - Resolve once per patient, as early as possible, then carry the identifier.
  - A returning patient is read from your own record, never re-resolved.
  - Never re-resolve mid-encounter; that is how one patient gets billed twice.
  - Casualty: treat first. Resolve on a temporary registration, reconcile after.
  - Admission requires an already-resolved identity.

SLOW OR UNAVAILABLE REGISTRY:
  - Set an explicit client timeout of 3-5 seconds.
  - Retry once reusing the same lookup reference so the attempt de-duplicates.
  - Cap the total wait; past it, change the screen rather than holding it.
  - Offer a pending path: open the encounter on a temporary identity, queue the
    lookup, reconcile on answer.
  - Track outstanding temporary identities and their age. An unreconciled temporary
    identity produces a claim that cannot be attached to a person.`}</AgentPrompt>

---

## /rail/guides/Benefit-Tree

# What a cover pays for

  A cover pays for things arranged as a tree rather than a flat catalogue. The tree starts at the
  benefit, and every level takes the code you chose at the level above it.

This page picks up where [02 · Verify cover](/rail/stops/Entitle) leaves off. That page
answers *which cover pays*. Once a cover is selected, this one answers *what it pays for, here,
today*.

Nothing below works without a chosen cover. The tree is resolved per member and per cover, so the
same query with a different selection comes back different.

The next three views show the same structure: the screens an operator works through, the shape
itself, and the calls behind them.

<Wireframe
  title="Benefits on the selected cover"
  actor="Clinical user · level 1"
  rows={[
    [
      { label: "Cover: TSC · contributor Margaret N***", kind: "text", span: 3, from: "effective coverage", note: "Always visible. The tree below belongs to this cover." },
      { label: "Search all levels", kind: "field", span: 1, note: "Returns leaves with their path, and it is the only way to find something you cannot place." },
    ],
    [
      { label: "Eye Health · SHA-05", kind: "text", swatch: 1, span: 3, from: "benefit code", note: "Read what the benefit declares here, because some payers answer the preauth question at this level" },
      { label: "Open", kind: "action", span: 1 },
    ],
    [
      { label: "Inpatient Services · PMF-07", kind: "text", swatch: 1, span: 3, from: "benefit code", note: "A different fund, in the same list" },
      { label: "Open", kind: "action", span: 1 },
    ],
  ]}
  caption={<>Level one is the only level you can ask for without already holding a code. Everything below it takes the code you just chose.</>}
/>

<Wireframe
  title="Categories under Eye Health"
  actor="Clinical user · level 2"
  rows={[
    [
      { label: "Eye Health", kind: "text", span: 4, from: "breadcrumb", note: "It holds the resolved chain you will need to explain a refusal, so it is doing more than decorating" },
    ],
    [
      { label: "Optical Health Services · SHA-05-SC-01", kind: "text", swatch: 1, span: 2, from: "sub_benefit_code" },
      { label: "Outpatient", kind: "text", span: 1, from: "access_point", note: "Declared here on this payer" },
      { label: "Open", kind: "action", span: 1 },
    ],
  ]}
  caption={<>The access point is usually decided at this level. Filter against the visit you are in, so the operator cannot pick something that cannot be billed.</>}
/>

<Wireframe
  title="Procedures under Optical Health Services"
  actor="Clinical user · level 3"
  rows={[
    [
      { label: "Eye Health › Optical Health Services", kind: "text", span: 4, from: "breadcrumb" },
    ],
    [
      { label: "Frames · SHA-05-034", kind: "text", swatch: 1, span: 2, from: "procedure code" },
      { label: "Preauth: Yes", kind: "field", tone: "negative", span: 1, from: "resolved from the chain", note: "Inherited or declared, and either way resolved" },
      { label: "Select", kind: "action", span: 1 },
    ],
    [
      { label: "Spectacle magnifiers · SHA-05-030", kind: "text", swatch: 1, span: 2, from: "procedure code", note: "No children, so this row selects rather than opens" },
      { label: "Preauth: Yes", kind: "field", tone: "negative", span: 1, from: "resolved from the chain" },
      { label: "Select", kind: "action", span: 1 },
    ],
    [
      { label: "Balance for this procedure, on this cover", kind: "field", tone: "attention", span: 4, from: "balance call", note: "A sideways question, asked with the procedure code and the contributor rather than the next level down" },
    ],
  ]}
  caption={<>Offer select on any node with no children, and open on any node that has them. Take the depth from the response instead of assuming it.</>}
/>

<Mermaid chart={`flowchart TD
    B["Benefit<br/><i>level 1, always present</i>"] --> C["Sub-benefit / category<br/><i>level 2</i>"]
    C --> P["Procedure<br/><i>level 3, the billable unit</i>"]
    P --> S["Service<br/><i>level 4, where a payer has one</i>"]
    S --> R["Protocol"]
    R --> D["Drug / item"]
    B -. "benefit code" .-> BAL(["Balance API<br/><i>asked, not traversed</i>"])
    P -. "procedure code" .-> BAL
`} />

<Mermaid chart={`sequenceDiagram
    autonumber
    actor C as Clinical user
    participant H as Your HMIS
    participant R as The rail

    H->>R: Benefits for this cover
    R-->>H: Benefit codes + what each declares
    C->>H: Picks Eye Health
    H->>R: Categories under SHA-05
    R-->>H: Sub-benefit codes + access points
    C->>H: Picks Optical Health Services
    H->>R: Procedures under SHA-05-SC-01
    R-->>H: Procedure codes + rules, tariffs, flags
    Note over H: Merge each level's attributes over<br/>what was inherited. Keep the chain.
    C->>H: Selects a procedure
    H->>R: Balance for this procedure, this contributor
    R-->>H: What is left, or "not tracked"
`} />

Whichever view you read, two things matter more than the levels themselves.

Balances are not a level of the tree. They are a separate question you ask *about* a node. Take the
benefit code, or the procedure code where the payer tracks it that finely, pass it to the balance
call, and you get what is left if that payer exposes it. Walking further down will never tell you
anything about a balance.

Fund, access point, tariff and preauthorisation are not levels either. They are *attributes* that
hang on whichever level the payer chose to attach them to. That is the part that trips people who
have integrated one payer and assume the next behaves the same way.

## The same rule can live at different depths

Of everything on this page, this is the part to hold on to, and it is why a hard-coded traversal
breaks on the second payer you integrate.

<Wire
  rows={[
    { call: "A private insurer", does: "May decide preauthorisation at the BENEFIT level: if the benefit is inpatient, preauthorisation is required, full stop. Nothing below it needs to be read to know that.", keep: "the flag, read at level 1" },
    { call: "The national scheme", does: "Decides it at the PROCEDURE level and downwards: two procedures inside the same category differ, and one of them needs approval while its neighbour does not.", keep: "the flag, read at level 3" },
  ]}
/>

So "does this need preauthorisation?" has no fixed home. Resolve the attribute against the whole
chain, from the benefit down to the node you have selected, and take the most specific value you
find. A traversal that only reads the leaf misses the insurer that declared it at the top, and one
that only reads the benefit misses the scheme that varies it per procedure.

The same is true of access point, of document requirements, and of combination rules.

  Carry a resolved context down the walk rather than a single node. At each level, merge what that
  level declares over what you inherited, and keep the node that declared each value so you can
  explain a refusal later. If your traversal returns a leaf object with no memory of its ancestors,
  you cannot answer "why is preauthorisation required here?", and somebody will ask.

## You walk it one level at a time

No call returns the whole tree, and that is not a limitation to route around. The tree is too large
to hand over, and the national scheme's procedure list alone runs to thousands of codes.

So every level takes the code chosen at the level above it — passed to the same route, as
`parent_code`, rather than to a route of its own.

<BuildSequence
  steps={[
    { do: "Ask for the benefits on the chosen cover", detail: "The call with no parent_code. This is the only level you can ask for without already having a code in hand." },
    { do: "Pass the benefit code as parent_code", detail: "You get its categories. Read what the benefit itself declared before you go further, because some payers have already answered your question here." },
    { do: "Pass the category code as parent_code", detail: "You get the billable procedures, each with its own attributes, which override anything inherited." },
    { do: "Pass the procedure code as parent_code", detail: "Where a payer exposes them, you get services, protocols and items. Many payers stop above this, and that is normal." },
    { do: "Ask the balance separately", detail: "A sideways question rather than the next step down — and one the rail does not yet answer against a selection. See below." },
  ]}
/>

Because the depth is a filter rather than a path, a client that stops when a level comes back empty
is already correct for every payer. One that hard-codes four calls is correct for exactly the payers
it was written against.

That has three consequences for the picker you build.

Take the depth from the response instead of assuming it. One payer's tree ends at the procedure,
another carries services and drugs below it. Follow what comes back, and offer a select action on
any node with no children.

A returned list may already start below the top. Because the tree is large, some responses answer
at the category or sub-procedure level rather than at the benefit, depending on the payer and how the
question was asked. Read the parent codes on every node and rebuild the chain rather than trusting
position in the response.

Search has to cross levels. A clinician looking for "dialysis" does not know which benefit it sits
under, and drill-down on its own will never get them there. Pair the walk with a search that returns
leaves and shows the path above each hit, so selecting a search result still gives you the resolved
chain.

## One shape, several vocabularies

The words change per payer while the structure stays the same, and the rail normalises to the
left-hand column.

| On the rail | SHA calls it | Others may call it |
|---|---|---|
| Benefit | Benefit (`SHA-07`, `PMF-07`) | Package, category, class |
| Sub-benefit / category | Sub-benefit, or "sub-package" (`SHA-07-SC-01`) | Sub-package, benefit group |
| Procedure | Intervention (`SHA-07-001`) | Service, item, tariff line, product |
| Service | Intervention component | Sub-service, activity |
| Protocol | Session or regimen rules | Care pathway, clinical protocol |
| Drug / item | Product | Item, consumable, SKU |

  Intervention is SHA's word. A private insurer's catalogue does not contain interventions, it
  contains services and items priced against a tariff. Writing the rail's docs in one payer's
  dialect makes every other integration read like an exception. Where a payload uses the payer's
  own name, the examples below keep it, and this table is how you map it back.

The traversal is what an operator sees as three screens. In your code it is one graph, and the
same query with a different member, facility or cover comes back different.

<ApiRef method="GET" path="/v1/benefits/coverage/" to="/rail-api/02-verify-cover" keep="benefit code">
  Level one of the tree: the benefits this member's cover carries, each with the parent codes needed to rebuild the chain. It is paginated, so read every page.
</ApiRef>

Read three things off that response.

The tree is per member. `beneficiary_cr_id` is a parameter, not a filter you could apply
afterwards. Two members at the same facility get different trees, and caching one member's tree
as "the benefit catalogue" is how a patient gets offered something they are not entitled to.

Several funds share one tree. `PMF-*` and `SHA-*` codes arrive interleaved, sorted by code
rather than grouped by fund. Group them yourself, and label the fund on screen, because a
clinician choosing "Inpatient" needs to know whether they are spending the national benefit or
the employer fund.

The pages are small by default. You get `count: 30` over `totalPages: 2` here, so a sync that
reads page one only ships two thirds of a tree and looks like it worked.

## What a procedure declares

<ApiRef method="GET" path="/v1/benefits/{sub_benefit_code}/interventions/" to="/rail-api/02-verify-cover" keep="procedure code">
  The billable procedures under one category, with every rule that governs them: tariffs per facility level, preauthorisation flags, payment mechanism, multi-session.
</ApiRef>

This is the densest object in the step. Every field on it changes behaviour somewhere later, and a
payer may declare any of them higher up instead, in which case what arrives here is what it
inherited.

<Wire
  rows={[
    { call: "level2Tariff … level6Tariff", does: "The price depends on the facility's level. A null at a level means not payable there at all, not free.", keep: "the tariff for YOUR level" },
    { call: "overallTariff", does: "0.00 alongside populated level tariffs does not mean free. It means price is resolved per level, so never quote this field to a patient.", keep: "—" },
    { call: "needsPreauth", does: "Sends you to 06 · Preauthorize before the work may be done. Readable here, hours before a patient is on a table.", keep: "the flag" },
    { call: "needsManualPreauthApproval", does: "A human has to approve, not just a system. That is a different waiting time and should be a different message on screen.", keep: "the flag" },
    { call: "requiresRenalPreauth, requiresOncologyPreauth", does: "Speciality-specific gates on top of the general one. Absent from most procedures, decisive on the ones that carry them.", keep: "the flags" },
    { call: "paymentMechanism", does: "FEE FOR SERVICE prices per item; PER DIEM prices per day. It changes what your billing screen even asks for.", keep: "the mechanism" },
    { call: "isMultisession", does: "One authorisation spanning several sessions, such as dialysis or chemotherapy cycles. Do not open a new case per session.", keep: "the flag" },
    { call: "activeForUhc", does: "Whether this procedure is live for the UHC fund specifically. False here while the cover is UHC means it is not payable.", keep: "the flag" },
  ]}
/>

  A procedure carries more than one price. Alongside the general level tariffs it may hold a separate
  set for a public-officer fund, and a fallback set that applies after a configured number of days.
  Which one applies depends on the fund the item is being billed to, and that fund is the effective
  coverage you froze earlier rather than a property of the procedure.

  So the price of an item depends on three things: the procedure, the facility level, and the cover
  it is billed against. Change the cover at billing and the price can change with it.

  Tariffs are keyed by facility level, and the level comes from the facility context you set at
  [00 · Authenticate](/rail/stops/Authenticate). A wrong or stale facility code does not fail
  here. It silently prices every line against another level's tariff, so read the level from the
  registry rather than storing it.

## The calls that walk it

<ApiRef method="GET" path="/api/v2/patients/{unique_patient_id}/eligibility/{selection_ref}/benefits" to="/rail-api/02-verify-cover" keep="code, access_point">
  Every level of the tree. Omit `parent_code` for the top level, then pass the code you chose to descend. `search` crosses levels, and `access_point` narrows a level to what is payable in the visit you are in.
</ApiRef>

The handle is the `selection_ref` from `covers/select`, not an eligibility reference: v2 has none.
Reading the tree also takes no consent proof — the proof is redeemed later, at
`POST /api/v2/claims/authorize`.

  Several benefits are not balance-tracked at all, among them ambulance and emergency, outpatient
  primary care, critical care and eye health. There is no pool to subtract from, so a screen
  that renders a balance for one of these is showing a number that means nothing.

  Public-officer schemes narrow it further, showing balances for a limited set of packages by
  default: outpatient, inpatient, eye, oral, maternity inpatient and excess-of-loss. Anything
  outside that list has no meaningful figure either.

  So a benefit has four honest states rather than two: available, nearly exhausted, exhausted,
  and not balance-tracked. Collapsing the fourth into "0.00" is the mistake to avoid.

  `allocated` and `available` come back null on procedures with no monetary ceiling, per-diem
  inpatient care being the usual case. Rendering null as `KES 0.00` tells a clinician the patient has
  nothing left, which is the opposite of what it means. Show "not applicable" and keep the
  distinction.

## Most limits count visits rather than money

Anyone arriving from private insurance has to unlearn this one. A limit here is as likely to be a
number of times as a sum of money.

<Wire
  rows={[
    { call: "Count-based", does: "One per year, one per week, dialysis twice weekly up to a yearly maximum. The limit is a tally of sessions or visits.", keep: "utilised visits, allocated visits" },
    { call: "Money-based", does: "A monetary ceiling per benefit, the shape private insurance uses throughout.", keep: "utilised amount, allocated amount" },
    { call: "Both, on one member", does: "Public-officer add-on covers behave like traditional insurance, so a member can hold count-based limits on their standard cover and money-based limits on the add-on, at the same time.", keep: "both, per cover" },
  ]}
/>

A balance screen that only knows how to render currency will show nothing useful for most
benefits. Read which kind you are holding before you format it.

Some employer schemes carry their own fund balances alongside the national ones. Where a cover
exposes them, they are read per benefit rather than per procedure.

<ApiRef method="GET" path="/api/v1/patients/benefits/utilization" to="/rail-api/02-verify-cover" keep="utilised, allocated">
  What has been used against a benefit, by patient and intervention code. It takes `patient_id` and `intervention_code` as query parameters and answers 400 without both.
</ApiRef>

  This one is not scoped to a `selection_ref`, so it does not answer "what is left on the cover I
  just froze onto this encounter". Read it as a utilisation figure for a patient and an
  intervention, and do not present it as the balance of the selected cover.

  The balance calls that were scoped that way — the per-procedure balance under an eligibility
  reference, and per-cover balances — answer 404 on dev. Everything above about untracked benefits,
  nulls and counts still holds for the figures you do get; there is simply no selection-scoped route
  to get them from today.

## What you keep

<Wire
  rows={[
    { call: "The procedure code", does: "The unit everything later prices against, with its access point and payment mechanism.", keep: "code, access_point" },
    { call: "The resolved chain", does: "Which level declared each attribute. It is what lets you explain a refusal rather than report one.", keep: "benefit → category → procedure" },
    { call: "The balance you read", does: "Where one exists. Note whose limit it was, and when it renews.", keep: "available, limit_applies_to" },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Bill",
      symptom: "\"The line was refused and the code looks correct\"",
      cause:
        "Access point mismatch. An inpatient-only procedure was selected during an outpatient visit, and nothing failed at selection time.",
    },
    {
      where: "Preauth",
      symptom: "\"Nobody told us this needed approving\"",
      cause:
        "The preauthorisation flag was declared somewhere in the chain and only the leaf was read. Resolve attributes against the whole chain.",
    },
    {
      where: "Any picker",
      symptom: "\"A clinician cannot find dialysis\"",
      cause:
        "Drill-down alone. A search that returns leaves with their path is the other half of the navigation.",
    },
    {
      where: "Bill",
      symptom: "\"It said covered, and the amount came back zero\"",
      cause:
        "A null allocated amount rendered as zero, or a household limit already spent. Null is not zero, and not every benefit is balance-tracked.",
    },
  ]}
/>

## What carries forward

The procedure code and its access point go to [06 · Preauthorize](/rail/stops/Preauth) where approval is
required, and to [07 · Bill](/rail/stops/Bill) where it is priced.

  Which cover pays: the covers a member holds, who contributes to each, what gets frozen onto the
  encounter, and when that choice stops being changeable.

<AgentPrompt title="Walk the benefit tree with an agent" filename="benefit-tree.instructions.md">{`You are integrating an HMIS with the Savannah unified payer rail.

Task: walk the benefit tree for a selected cover, and read a balance.

THE TREE
  Benefit -> sub-benefit/category -> procedure -> service/protocol/item.
  It starts at the benefit and is resolved PER MEMBER and PER COVER. Do not cache one
  member's tree as "the catalogue".
  There is no call that returns the whole tree. ONE route returns every level:
    GET /api/v2/patients/{unique_patient_id}/eligibility/{selection_ref}/benefits
    no parent_code  -> the top level
    parent_code=<code chosen above>  -> that node's children
    also takes: search (crosses levels), access_point, page, page_size
  The handle is selection_ref from POST /api/v2/patients/{unique_patient_id}/covers/select.
  There is no eligibility_ref in v2, and reading the tree takes no consent proof.
  Do not assume a fixed depth: follow what comes back, and offer select on any node with no
  children.
  Responses may answer below the top level. Read parent codes and rebuild the chain rather
  than trusting position.

ATTRIBUTES CAN BE DECLARED AT ANY LEVEL
  One payer sets preauthorisation at the BENEFIT level; another sets it per PROCEDURE, with
  neighbours differing. The same is true of access point, document requirements and
  combination rules.
  Carry a resolved context down the walk: at each level merge what that level declares over
  what you inherited, take the most specific value, and keep which node declared it so a
  refusal can be explained.

BEFORE SELECTING A PROCEDURE, READ FOUR THINGS
  code, access_point (filter to the CURRENT visit), needs_preauth, payment_mechanism.
  An inpatient-only procedure chosen in an outpatient visit is refused at Bill, not here.

BALANCES
  A sideways question, not a level. There is no selection-scoped balance route on the rail
  today: GET /api/v1/patients/benefits/utilization takes patient_id + intervention_code and
  is NOT scoped to the cover you selected. Do not present it as the selected cover's balance.
  NOT EVERY BENEFIT IS BALANCE-TRACKED. Render a "not tracked" state; never show 0.00 for
  an untracked benefit.
  Limits are as often COUNTS as money. Detect which you hold before formatting.
  Informational, not a gate: an absent balance must not block selection, the visit or the
  claim.

NAVIGATION
  Pair drill-down with a cross-level search that returns leaves and shows the path above
  each hit.`}</AgentPrompt>

---

## /rail/guides/Clinician-Identity

# Resolving the clinician

  A registration number without its regulator fails the same way a patient identifier without its
  document type fails. Neither one resolves, and both come back as a false "not found".

This page continues [01 · Identify](/rail/stops/Identify), which resolves the patient. Here you ask
the same question about whoever is treating them, and the answer is what keeps a billed line
defensible months later.

Every billed line carries the clinician who performed it, their licence, and the body that
regulates them. Resolve all three here and the line holds up later. This is also the cheapest
point at which you can find out that a licence has lapsed.

The clinician gets asked the same question as the patient: who are you, and does your paperwork
hold up? You answer it the same way, by picking the regulator, entering the registration number
and resolving one practitioner.

Populate the regulator picker the way you populated the document-type picker, from the
terminology service rather than a constant.

  `HEALTHCARE-WORKER-REGULATORS` is the name we expect this vocabulary to carry, and it has not been
  verified against the live catalogue. Confirm it before you wire it in. One call does it:
  `GET /code-systems/?search=regulator`, or [browse the catalogue](/rail/reference/Terminology-Getting-Data#for-a-program--paged-json).
  Short codes are stored upper-case, and the detail route resolves either a short code or an id, so a
  404 is a real answer rather than an addressing mistake.

<ValueSet
  system="HEALTHCARE-WORKER-REGULATORS"
  label="Healthcare worker regulators"
  what="The bodies that register practitioners: KMPDC for medical practitioners and dentists, the Clinical Officers Council, the Nursing Council of Kenya and the rest. Each issues its own numbering, so the regulator is half of the identifier."
/>

<Wireframe
  title="Attending doctors"
  actor="Clinician selection"
  rows={[
    [
      { label: "Regulator", kind: "field", span: 2, from: "regulator", note: "KMPDC · Clinical Officers Council · Nursing Council of Kenya" },
      { label: "Registration number", kind: "field", span: 1, note: "As issued by that regulator" },
      { label: "Search", kind: "action", span: 1 },
    ],
  ]}
  caption={<>A registration number means nothing without the body that issued it. Same pairing rule as a patient identifier.</>}
/>

Searched, with a result to select:

<Wireframe
  title="Attending doctors, 1 match"
  actor="Clinician selection"
  rows={[
    [
      { label: "KMPDC", kind: "field", span: 2, from: "regulator" },
      { label: "A8***1", kind: "field", span: 1, from: "registration_number" },
      { label: "Search", kind: "action", span: 1 },
    ],
    [
      { label: "A8***1", kind: "text", span: 1, from: "registration_number", note: "Masked" },
      { label: "Dr John W*** M***", kind: "text", span: 2, from: "name", note: "Masked. Show only what confirms the right clinician" },
      { label: "Not suspended", kind: "field", tone: "positive", span: 1, from: "suspension", note: "Checked live rather than cached" },
    ],
    [
      { label: "Select doctor", kind: "action", span: 4, note: "Attaches this practitioner to the case" },
    ],
  ]}
  caption={<>Licence status is the point of the call. A suspended or lapsed practitioner means a claim rejected days later, or a refusal here while it can still be fixed.</>}
/>

The same screen when the licence does not hold up:

<Wireframe
  title="Attending doctors, 1 match"
  actor="Clinician selection"
  rows={[
    [
      { label: "KMPDC", kind: "field", span: 2, from: "regulator" },
      { label: "B2***7", kind: "field", span: 1, from: "registration_number" },
      { label: "Search", kind: "action", span: 1 },
    ],
    [
      { label: "B2***7", kind: "text", span: 1, from: "registration_number", note: "Masked" },
      { label: "Dr Alice N*** K***", kind: "text", span: 2, from: "name", note: "Masked" },
      { label: "Suspended", kind: "field", tone: "negative", span: 1, from: "suspension", note: "Live from the regulator rather than a cached copy" },
    ],
    [
      { label: "Cannot be selected", kind: "text", span: 4, note: "Say why here, while another clinician can still be chosen, instead of at billing days after the care was given." },
    ],
  ]}
  caption={<>The same layout with one cell different, and that cell is the reason for making the call.</>}
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    actor C as Clinical user
    participant H as Your HMIS
    participant R as The rail
    participant W as Health worker registry

    C->>H: Picks regulator, enters registration number
    H->>R: Practitioner search (regulator + number)
    R->>W: Resolve and check licence
    W-->>R: Practitioner, cadre, speciality, suspension state
    R-->>H: One practitioner to select
    C->>H: Select doctor
    Note over H,R: Keep the registration number and its regulator.<br/>Licence status is re-checked at preauth and billing.
`} />

<Mermaid chart={`flowchart TD
    A["Regulator + registration number"] --> B{Practitioner found?}
    B -- No --> N["Re-check the regulator<br/>before re-typing the number"]
    B -- Yes --> C{Licence current, not suspended?}
    C -- No --> D["Refuse now. Do not attach.<br/>Choose another clinician"]
    C -- Yes --> E["Attach to the case, keeping the<br/>registration number and its regulator"]
`} />

<Operation
  method="GET"
  path="/api/v1/professionals"
  summary="Resolve one practitioner, with a licence verdict."
  params={[
    { name: "X-Facility-Id", type: "header", required: true, description: "The facility this call is made from." },
    { name: "X-Facility-Id-Type", type: "header", required: true, description: "How to read it: mfl, license-number, fr-code, registration-number or fid." },
    { name: "identification_number", type: "query", required: true, description: "The number as the regulator issued it." },
    { name: "identification_type", type: "query", required: true, description: "registration_number is preferred." },
    { name: "regulator", type: "query", required: false, description: "KMPDC, COC or NCK. Required for every lookup except a PUID one." },
  ]}
  response={`{
  "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" }
}`}
/>

`licence.status` is `ACTIVE`, `SUSPENDED`, `EXPIRED` or `UNKNOWN`. You get the verdict rather
than the raw material. The registry answers with an activity flag and a set of date ranges, and
every integrator who works a verdict out of those works it out slightly differently. At least
one of those versions is wrong, and that cost turns up days later as a rejected line.

`UNKNOWN` is the honest answer when the registry did not respond, and it must never render as
"not suspended". Treat it as a stop rather than a pass.

A suspended practitioner comes back as a 200 with a negative verdict rather than an error. The
API reports the fact and your UI refuses the selection. Only a malformed request, or a pair that
resolves to nothing, is a 4xx:

```bash
curl -sS "$RAIL_BASE_URL/api/v1/professionals?identification_number=A81234\
&identification_type=registration_number&regulator=KMPDC" \
  -H "Authorization: Bearer $RAIL_TOKEN" \
  -H "X-Facility-Id: FAC-2029" \
  -H "X-Facility-Id-Type: fr-code"
```

Drop `regulator` and you get `REGULATOR_REQUIRED` rather than a false not-found. It is the same
failure as sending an identifier without its type, and it is caught explicitly because it is the
mistake people actually make.

Four things the registry buys you, in order of how much they save.

<BuildSequence
  steps={[
    {
      do: "Refuse a lapsed licence early",
      detail:
        "Licence validity is checked again at preauthorisation and at billing. Checking it when the clinician is selected turns a claim rejected days later into a conversation you can still have. It is the most valuable check the registry gives you, and the one integrations most often skip.",
    },
    {
      do: "Reach a practitioner when you have to",
      detail:
        "Some interventions need a named clinician's sign-off before they can go ahead. The registry holds the contact details for reaching that person, where an internal directory may be stale. The request itself is made at 06 · Preauthorize; what matters here is that you resolved a real person instead of a typed name.",
    },
    {
      do: "Confirm speciality where the benefit demands it",
      detail:
        "Some procedures require a credentialed practitioner of a named speciality, sometimes an anaesthetist alongside a surgeon. Checking at scheduling is cheaper than discovering it at adjudication.",
    },
    {
      do: "Populate the picker from the registry",
      detail:
        "Build the clinician dropdown from the registry instead of from a table someone typed. Taking the licence and regulator from the registry removes a whole class of rejection.",
    },
  ]}
/>

Cadre and speciality are coded lists too. You need them when a benefit requires a named
speciality, and when a practitioner picker groups by discipline. `PRACTITIONER-CADRES` is
unconfirmed in the same way as the regulator list above, so search the catalogue for `cadre`
before you depend on the name.

<ValueSet
  system="PRACTITIONER-CADRES"
  label="Cadres and specialities"
  what="The discipline a practitioner is registered under, and the specialities within it. Needed where a benefit requires an approved practitioner of a named speciality, and for grouping a clinician picker by something other than surname."
/>

  KMPDC, the Clinical Officers Council and the Nursing Council of Kenya each issue their own
  numbers, and the same digits can be valid under two of them. A registration number without
  its regulator fails the way a national ID without its type fails, and it produces the same
  false "not found".

## What you keep

<Wire
  rows={[
    { call: "Registration number + regulator", does: "Together they are the clinician's identifier. Neither one is enough on its own.", keep: "both, on the encounter" },
    { call: "The licence verdict", does: "Read live at selection, then re-checked at preauthorisation and billing. Store when you read it as well as what it said.", keep: "status + when" },
    { call: "Cadre and speciality", does: "Needed where a benefit requires a named speciality, and for grouping a clinician picker.", keep: "the codes" },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Clinician selection",
      symptom: "\"That registration number does not exist\"",
      cause:
        "The wrong regulator. The same digits can be valid under two councils, so the number means nothing without the body that issued it.",
    },
    {
      where: "Billing",
      symptom: "\"Line rejected: practitioner not eligible\"",
      cause:
        "A lapsed or suspended licence, or the wrong speciality for the intervention. Licence status is checked live at billing; checking it at selection turns this into a fixable conversation.",
    },
    {
      where: "Billing",
      symptom: "\"We cannot say who performed this\"",
      cause:
        "The clinician was picked from a typed internal list rather than the registry, so the line carries a name with nothing behind it.",
    },
    {
      where: "Preauth",
      symptom: "\"The surgical request was refused on the practitioner\"",
      cause:
        "A surgical request needs a credentialed surgeon, not just a licensed doctor. Where an anaesthetist is required, that is a second named practitioner.",
    },
  ]}
/>

## What carries forward

The registration number and its regulator travel onto every billed line, and the licence is
re-checked at [06 · Preauthorize](/rail/stops/Preauth) and [07 · Bill](/rail/stops/Bill). Where an
intervention needs clinical sign-off, the request is routed to this practitioner, and that
workflow lives at Preauth rather than here.

  The patient's identity: the identifier pair, the four moves of a lookup, and what resolving it
  hands to every step after.

<AgentPrompt title="Resolve the clinician with an agent" filename="clinician-identity.instructions.md">{`You are integrating an HMIS with the Savannah unified payer rail.

Task: resolve the treating clinician, and keep what a claim will need.

THE IDENTIFIER IS A PAIR
  Registration number + the regulator that issued it. The same digits can be valid under
  two councils, so a number alone produces a false "not found".
  Populate the regulator picker from the terminology service, never from a constant.

CHECK THE LICENCE AT SELECTION
  Read the verdict live. Refuse a suspended or lapsed practitioner at the point they are
  chosen. Do not attach them and find out at billing, days after the care was given.
  Store what the verdict was AND when you read it.

SPECIALITY MATTERS WHERE THE BENEFIT SAYS SO
  Surgical requests need a credentialed surgeon, not merely a licensed doctor, and some
  procedures additionally require an anaesthetist as a second named practitioner.
  Cadre and speciality are coded lists; fetch and cache them like any other.

BUILD THE PICKER FROM THE REGISTRY
  Not from a typed internal table. Every billed line carries the performing clinician,
  their licence and their regulating body; sourcing those from the registry removes an
  entire class of rejection.

MASK ON SCREEN
  Show enough to confirm the right clinician, not the full record.`}</AgentPrompt>

---

## /rail/guides/Orders-And-Prescriptions

# Orders, results and prescriptions

  An order and a prescription have the same shape. Something is requested here, performed
  somewhere else, and answered back. Write the routing once and it covers both.

  The order surface on this page is designed and not yet built: no `/orders` prefix is registered
  in the service under either version, and neither is `/api/v1/visits/{visit_id}/orders`. Every
  order and result call here answers 404 today.

  The prescription calls below are real. Read the order half as the shape that is coming — it is
  what the rail is being built to — and do not schedule work against it until the routes land.

## What changes when the request leaves the building

Inside one HMIS, ordering a test is a database write. The requester and the performer share a
schema, so "routed to the lab" means a row with a status on it.

On the rail the performer may be a different organisation, running different software, in a
different town. That works because neither side integrates with the other. Both are already
on the rail, and the rail does the routing.

<Wire
  rows={[
    { call: "You order", does: "A lab test, an image or a procedure. You name what you want and who should do it, and you never connect to them directly.", keep: "order_id" },
    { call: "They see it", does: "The order lands in the performing facility's inbox as work, whether they run your software or somebody else's.", keep: "their queue" },
    { call: "They answer", does: "Results are returned against the order and reach you as the requester. You do not build a second integration, and you do not poll a result mailbox per partner.", keep: "result_ref" },
  ]}
/>

## Orders

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/orders" to="/rail-api/05-treat">
  Order a lab, an image or a procedure, with the diagnosis that justifies it.
</ApiRef>

Three things about the response are worth building for.

<Wire
  rows={[
    { call: "Panels expand", does: "An ordered panel comes back as its constituent parameters, each with its own code and reference range. The rail does that expansion, so do not keep a panel-to-parameter table of your own.", keep: "expanded_parameters[]" },
    { call: "Routing is a state you read", does: "routed means the performer has it. If they are briefly unreachable the order is held and retried. That is not a failure, and it must not make you raise a second order.", keep: "status" },
    { call: "The reason travels", does: "The diagnosis on the order is what a payer reads later to decide whether the test was indicated. An order with no reason can still be billed, and it can just as easily be rejected.", keep: "reason[]" },
  ]}
/>

<ApiRef method="GET" path="/api/v1/orders?performer_facility=" to="/rail-api/05-treat">
  The orders routed to this facility. This is your work queue, and it holds requests from every requester on the rail.
</ApiRef>

A facility that only ever posts orders has built half the feature. The inbox is what makes
you a performer as well as a requester, and it is the same call whether the request came from
your own clinician or from a facility two counties away.

## Results

<ApiRef method="POST" path="/api/v1/orders/{order_id}/results" to="/rail-api/05-treat">
  Return the result. It reaches the requester, and it lands in the patient's record.
</ApiRef>

Return observations against the expanded parameter list the order came back with, rather than
against your own panel definition. A result that carries observations the order did not ask
for, or misses ones it did, is refused with `RESULT_ORDER_MISMATCH` instead of being stored
quietly against the wrong codes.

A result written this way does three jobs at once. It answers the requester, it becomes an
`Observation` in the shared record, and it is the evidence behind the line when the claim is
assessed. That is why you record clinically instead of billing directly.

  `status: preliminary` is a legitimate return and clinicians act on it. Send it when you have
  it and supersede it with `final`. A system that holds everything back until verification
  keeps the requester waiting for information the lab already has.

## Prescriptions

The prescription is the case where routing matters most, because the patient chooses where to
fill it, and that is usually not where it was written.

<ApiRef method="POST" path="/api/v1/prescriptions" to="/rail-api/05-treat">
  Prescribe, routed to the pharmacy the patient names.
</ApiRef>

<Anatomy
  cards={[
    {
      title: "Per item",
      required: ["medication", "dose", "route", "frequency", "duration_days", "quantity"],
      optional: ["substitution_allowed", "instructions"],
      note: "medication is coded, with KEML as the national list. A free-text drug name gives you a prescription no other system can dispense against.",
    },
    {
      title: "Per prescription",
      required: ["diagnosis", "prescriber"],
      optional: ["route_to_facility"],
      note: "Omit route_to_facility and the prescription is open, so any pharmacy on the rail can claim it. Name one and only that pharmacy sees it.",
    },
  ]}
/>

## Pulling what was routed to you

<ApiRef method="GET" path="/api/v1/prescriptions" to="/rail-api/05-treat">
  Prescriptions written anywhere on the rail and routed to this pharmacy.
</ApiRef>

This call is what takes paper off the pharmacy counter. The patient arrives with an identity
rather than a slip, and you pull what was written for them and dispense against it.

<ApiRef method="POST" path="/api/v1/prescriptions/dispense" to="/rail-api/05-treat">
  Record what was actually handed over, including a partial fill or a substitution.
</ApiRef>

<Wire
  rows={[
    { call: "Partial fills accumulate", does: "Dispensing 10 of 24 leaves 14. The next dispense, possibly at another pharmacy, reads what remains, and anything over that is refused.", keep: "quantity_remaining" },
    { call: "Substitution follows the prescriber's flag", does: "Where the prescriber set substitution_allowed: false, a different product is refused. Send it back to the prescriber instead.", keep: "substitution_allowed" },
    { call: "Bill what was dispensed", does: "A pharmacy line traces back to the dispense record rather than to the prescription, so bill the fill.", keep: "dispense_id" },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Treat",
      symptom: "\"We raised the order twice because it looked stuck\"",
      cause: "routed means held and retrying rather than failed. A duplicated order produces a duplicated specimen and two results against one clinical question.",
    },
    {
      where: "Treat",
      symptom: "\"The result came back and the codes did not match anything\"",
      cause: "Results were returned against a local panel definition rather than the expanded parameters the order carried.",
    },
    {
      where: "Treat",
      symptom: "\"The pharmacy cannot see the prescription\"",
      cause: "It was routed to a named facility that is not this one. Re-route it rather than re-writing it.",
    },
    {
      where: "Bill",
      symptom: "\"We billed the prescription and were short-paid\"",
      cause: "The patient took a partial fill. The dispense is the billable event, not the prescription.",
    },
  ]}
/>

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 502 | `ORDER_PERFORMER_UNREACHABLE` | The performing facility has not accepted the order yet. |
| 409 | `RESULT_ORDER_MISMATCH` | Observations returned do not match the order's parameters. |
| 403 | `PRESCRIPTION_NOT_ROUTED_HERE` | Dispensing against another pharmacy's prescription. |
| 409 | `DISPENSE_EXCEEDS_PRESCRIBED` | Cumulative dispensed quantity is over the prescribed one. |
| 409 | `SUBSTITUTION_NOT_ALLOWED` | A substitute was dispensed where the prescriber forbade it. |

  Sending a specimen to a hub is an order that also has to travel. The authorisation the
  patient gave you moves with the referral, so they do not have to give it again at the other
  end.

---

## /rail/guides/Paperless

# Going paperless on day one

  A discharge summary is a view of clinical data that has already been recorded, not something a
  person has to sit down and write. Record the data and the document comes free.

## The reason paperless usually fails

Claims require documents: a discharge summary, a claim form, a treatment sheet, a signed
consent. Most systems meet that requirement by asking a person to write the document, into a
word processor or into a form that produces a PDF, and then to attach it.

That is the paper workflow with the paper taken out. It still costs a person per claim, it still
happens at the end when everyone is in a hurry, and the documents it produces still disagree
with the clinical record they were transcribed from.

The alternative is to render documents rather than author them. Every field a discharge summary
contains, the diagnosis, the encounter dates, the medications, the results and the clinician, is
already recorded at [05 · Treat](/rail/stops/Treat). The document is a projection of that
record.

<Wire
  rows={[
    { call: "You record clinical facts", does: "Diagnoses, observations, orders, results and prescriptions, coded as the encounter runs. This is the work, and you were doing it anyway.", keep: "the record" },
    { call: "The rail renders documents", does: "It knows which documents this claim requires, and it holds the data each of them is made of. Ask for them and it produces them.", keep: "document_id" },
    { call: "Nobody types a summary", does: "A new HMIS on the rail is paperless the day it connects, without building a document editor, a template engine or a PDF pipeline.", keep: "the capability, for free" },
  ]}
/>

## Generate what the claim requires

  No document routes exist under a visit, so the two calls on this page answer 404 today. What is
  live sits at a different address and is scoped differently: `POST /api/v1/clinical/html-to-pdf`
  converts HTML you supply, and `GET /api/v1/clinical/document-bundles/{id}/render` and
  `POST /api/v1/clinical/document-bundles/{id}/pdf` render a bundle.

  So a facility that needs a PDF today can have one. What it cannot do yet is ask the rail to
  assemble the required document set from the clinical data already recorded, which is the part
  this guide is about.

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/documents/generate" to="/rail-api/05-treat">
  Generate the documents this visit's items require, from the clinical data already recorded.
</ApiRef>

The response is per document, and the one worth reading is the document that could not be built.

```json
{
  "documents": [
    { "document_type": "DISCHARGE_SUMMARY", "status": "generated", "attached_to_visit": true, "missing": [] },
    { "document_type": "CLAIM_FORM", "status": "incomplete", "missing": ["encounter.period.end", "diagnosis.primary"] }
  ]
}
```

`missing[]` names clinical elements rather than form fields. The fix is to record the fact, so
close the encounter or rank the primary diagnosis instead of typing anything into a document.
A system that treats `missing[]` as a validation error on a form has rebuilt the thing this
replaces.

  Which documents a claim needs comes from the interventions billed on it, read at
  [02 · Verify cover](/rail/stops/Entitle) and checked again at
  [08 · Submit](/rail/stops/Submit). Generate against that list rather than a fixed set, or you
  will produce three documents where one was required, and miss the one that was.

## Render on demand

<ApiRef method="GET" path="/api/v1/visits/{visit_id}/documents/{document_type}/render?format=html" to="/rail-api/05-treat">
  Render a document to show on screen, or as a PDF to hand over and sign.
</ApiRef>

<Wire
  rows={[
    { call: "HTML", does: "For display inside your own UI, in a clinician's review screen, in a patient portal. It is styled to be embedded rather than printed.", keep: "the markup" },
    { call: "PDF", does: "For the cases where a physical artefact is genuinely required, such as a signature, a hand-over, or a regulator who asks for one.", keep: "the file" },
    { call: "Deterministic from the record", does: "Render the same visit twice and you get the same document. You never have to store a snapshot, because you can ask for the view again.", keep: "nothing" },
  ]}
/>

Do not cache the rendered artefact as your source of truth. The record is the truth and the
document is derived from it, so a stored PDF goes stale the moment a result is amended. Store the
`document_id` that was attached to the claim, since that is the version the payer assessed, and
render fresh for everything else.

## What this gives an HMIS that has never had it

<BuildSequence
  steps={[
    {
      do: "A small clinic connects and is paperless",
      detail:
        "It needs no document editor, no template library and no PDF service. It records clinically, asks for documents, and attaches what comes back.",
    },
    {
      do: "The documents always match the record",
      detail:
        "Nothing is transcribed between the two, so what was billed, what was recorded and what the payer reads cannot drift apart.",
    },
    {
      do: "Attachment failures move upstream",
      detail:
        "MISSING_DOCUMENTS at submission becomes DOCUMENT_DATA_INCOMPLETE while the encounter is still open, naming the clinical gap while somebody can still close it.",
    },
    {
      do: "The same data serves four purposes",
      detail:
        "One recording becomes the claim's evidence, the shared health record, the referral's payload, and the document set. You capture it once, at the point it was true.",
    },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Submit",
      symptom: "\"Generation says incomplete and we cannot see why\"",
      cause: "Read missing[]. It names clinical elements, so record the fact rather than looking for a form field to fill.",
    },
    {
      where: "Submit",
      symptom: "\"We attached a summary we wrote and it was queried\"",
      cause: "A hand-written document disagrees with the coded record behind the claim. Generate it instead; the assessor is reading both.",
    },
    {
      where: "Treat",
      symptom: "\"The PDF we stored is out of date\"",
      cause: "A rendered document is a view rather than a record. Keep the document_id that was attached and re-render everything else.",
    },
  ]}
/>

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 422 | `DOCUMENT_DATA_INCOMPLETE` | The clinical data the document renders from is missing elements. |
| 422 | `MISSING_DOCUMENTS` | A required document was never attached. Checked at [08 · Submit](/rail/stops/Submit). |

  Back to the stop that records the data all of this is generated from.

---

## /rail/guides/Referrals

# Referrals, samples and one authentication

  A patient authenticated at the dispensary that referred them should not have to authenticate
  again at the hospital they were referred to. The proof travels with the referral.

  No `/referrals` prefix is registered in the service, and there is no referral surface behind the
  gateway at all — every call on this page answers 404 today, the specimen routing included.

  What follows is the design the rail is being built to, and it is worth reading before you model
  referrals yourself. It is not something you can integrate against yet.

## Hub and spoke, without building hub and spoke

A referral network is normally a project: agreements between facilities, an integration per
partner, a shared directory, a way to move documents. Every new spoke is new work.

On the rail it is a call. Both facilities are already connected, both are already resolved
against the facility registry, and the clinical record is already in a form the other side can
read. Referral is what those things add up to.

<Wire
  rows={[
    { call: "You refer", does: "Name the receiving facility and the service you want. The clinical record goes with it. A referral is not a letter asking them to start again.", keep: "referral_id" },
    { call: "They see it before the patient arrives", does: "An inbound referral is in their queue with the diagnosis, the investigations already done and the results already back.", keep: "their inbox" },
    { call: "They accept, and the visit opens", does: "Acceptance opens the receiving visit against the authorisation the source took. The patient walks in already known.", keep: "visit_id" },
  ]}
/>

## Refer

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/referrals" to="/rail-api/05-treat">
  Refer onward, carrying the record and the authorisation taken here.
</ApiRef>

`include_clinical: true` is the field that decides whether this is a referral or a note. With
it, the receiving clinician opens the patient and sees the encounter, the conditions, the
observations and any results already returned. That is the difference between a hub that
repeats the workup and one that continues it.

<ApiRef method="GET" path="/api/v1/referrals?direction=inbound" to="/rail-api/05-treat">
  Referrals sent to this facility, with the record and the authorisation attached.
</ApiRef>

<ApiRef method="POST" path="/api/v1/referrals/{referral_id}/accept" to="/rail-api/05-treat">
  Accept or decline, and open the receiving visit against the source authorisation.
</ApiRef>

Accept the referral before you open a visit. A visit opened against an unaccepted referral is
refused with `REFERRAL_NOT_ACCEPTED`. Acceptance is what binds the source authorisation to the
new encounter, so skipping it sends the patient back to authenticate.

## One authentication, at the facility they were standing in

Build the workflow around this feature, because it is the one patients notice.

Consent on the rail is proof that a member was present and willing. Ordinarily it is taken
where the care happens. On a referral that rule would mean a patient authenticates at the
dispensary, travels to the county hospital, and authenticates again for the same episode,
often returning a second day because the biometric device was down or the phone that receives
the code was left at home.

<BuildSequence
  steps={[
    {
      do: "Take the authorisation once, at the source",
      detail:
        "The patient is standing in front of you. Whatever modality the payer requires (a one-time code, biometrics, a guardian) is collected here, at [03 · Consent](/rail/stops/Consent), and produces an authorization_ref.",
    },
    {
      do: "Send it with the referral",
      detail:
        "authorization_ref travels on the referral. The response echoes back where it was authenticated, whether the destination will honour it, and when it expires.",
    },
    {
      do: "The destination opens against it",
      detail:
        "Accepting the referral opens the receiving visit bound to that authorisation. The patient does not give consent a second time, on a second device, at the end of a second journey.",
    },
    {
      do: "Show the patient the window, at the source",
      detail:
        "The authorisation has an expiry. Tell the patient when they are referred, not when they arrive. This is the one failure mode the design does not remove.",
    },
  ]}
/>

  Read `authorization.honoured_at_destination` from the referral response rather than assuming
  it. Where a payer requires re-authentication at the point of service for a benefit, it comes
  back false, and the receiving facility must capture consent as normal. If you build only for
  the happy path, the patient gets turned away at a desk that cannot explain why.

If the patient arrives after the window has closed, the destination gets
`REFERRAL_AUTH_EXPIRED`. That is a prompt to re-authenticate there, rather than a rejected
referral. The clinical record and the acceptance both stand.

## Samples travel the same way

A specimen sent to a hub laboratory is an order with a journey attached. The order says what
to do; the sample record says what physically moved, and lets both ends see where it is.

<ApiRef method="POST" path="/api/v1/referrals/{referral_id}/samples" to="/rail-api/05-treat">
  Send a specimen against the order that asked for it.
</ApiRef>

<Wire
  rows={[
    { call: "The sample is tied to the order", does: "Not to a courier manifest. The result comes back against the order, so the requesting clinician sees it in the patient's record rather than in an email.", keep: "order_id" },
    { call: "Cold chain is declared, not assumed", does: "A specimen that must stay cold says so, and a hub that cannot honour it declines on receipt rather than running a test on a degraded sample.", keep: "cold_chain" },
    { call: "Rejection is a state with a reason", does: "The reason reaches the sender (haemolysed, insufficient, unlabelled), who can recollect while the patient may still be reachable.", keep: "the reason" },
  ]}
/>

A spoke that can send samples can offer tests it cannot perform. That is the commercial
argument for the referral feature, and it is the same three calls as everything else on this
stop.

## What breaks here

<CostTable
  rows={[
    {
      where: "Treat",
      symptom: "\"The patient was sent back to authenticate again\"",
      cause: "The receiving visit was opened directly instead of through referral acceptance, so nothing bound the source authorisation to it.",
    },
    {
      where: "Treat",
      symptom: "\"They arrived and the authorisation had expired\"",
      cause: "The window was never shown at the source. Surface the expiry when the referral is written, on the patient's copy.",
    },
    {
      where: "Treat",
      symptom: "\"The hospital started the workup from scratch\"",
      cause: "include_clinical was false, so the referral carried a reason and nothing else.",
    },
    {
      where: "Treat",
      symptom: "\"The result went to the hub, not to us\"",
      cause: "The sample was sent without the order it belongs to. Results route by order, not by facility.",
    },
  ]}
/>

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 409 | `REFERRAL_NOT_ACCEPTED` | A visit was opened against a referral nobody accepted. |
| 409 | `REFERRAL_AUTH_EXPIRED` | The source authorisation's window closed before arrival. |
| 403 | `CLINICAL_CONSENT_MISSING` | The patient's proof does not cover sharing the record onward. |

  Everything a referral carries was recorded once, as clinical data. The same recording is what
  lets the rail generate the documents a claim needs, instead of somebody typing them.

---

## /rail/reference/Errors

# Error dictionary

  An error tells you what happened, where in the request it happened, and which screen can
  fix it. If your UI shows only the first, the operator never sees the two parts they could
  have acted on.

## The shape

Every error the rail returns has the same body:

```json
{
  "error": "MISSING_DOCUMENTS",
  "message": "Itemised Invoice (final_bill) is still missing for TBC-4471-2026.",
  "path": "lines[].documents",
  "fix_stage": "billing"
}
```

| Field | What it is for |
|-------|----------------|
| `error` | The stable code. Switch on this, never on `message`. |
| `message` | Human-readable, written for the person at the desk. Display it, but do not parse it. |
| `path` | Where in the request the problem is, so you can highlight the offending field. |
| `fix_stage` | Which stage of the workflow can resolve it. This is the routing hint for your UI. |

Two rules follow from this shape.

Validation returns every reason at once, so you will not fix one error and then discover a
second behind it. A correction round stays one round instead of turning into a queue.

Codes are `UPPER_SNAKE_CASE`, always. A lowercase error code in a response is a defect.
Report it rather than coding around it.

## The dictionary

<ErrorDictionary />

## Retrieve it instead of transcribing it

The dictionary above is generated from one source, and that source is published as
terminology. Generate your enum from it rather than hand-copying a table that will drift.

<Wire
  rows={[
    {
      call: "GET /terminology/rail-errors.json",
      does: "Flat list: code, http, stop, fix_stage, meaning, fix",
      keep: "codes[]",
    },
    {
      call: "GET /terminology/rail-errors.codesystem.json",
      does: "CodeSystem, with http/stop/fix_stage as concept properties",
      keep: "concept[]",
    },
    {
      call: "GET /terminology/rail-errors.valueset.json",
      does: "ValueSet, pre-expanded",
      keep: "expansion.contains[]",
    },
  ]}
/>

<div className="rail-op-actions">
  <a className="rail-btn rail-btn--primary" href="/terminology/rail-errors.json" download>
    Download flat JSON
  </a>
  <a className="rail-btn" href="/terminology/rail-errors.codesystem.json" download>
    CodeSystem
  </a>
  <a className="rail-btn" href="/terminology/rail-errors.valueset.json" download>
    ValueSet
  </a>
</div>

The same set is loadable from the terminology service alongside every other value set the
rail uses. See [Value sets and code systems](/rail/reference/Value-Sets) for how to query it
there, and how to keep a local copy in sync.

## How to build against errors

<BuildSequence
  steps={[
    "Generate your error enum from the published value set at build time. A hand-maintained copy drifts the first week a code is added.",
    "Switch on `error`, never on `message`. Messages are written for humans, and their wording will change.",
    "Route on `fix_stage`. Send the operator to the screen that can resolve the problem instead of showing a message and leaving them to hunt for it.",
    "Show every reason at once. The API returns them together, and collapsing them down to a single first error puts back the queue the contract was written to remove.",
    "Treat 502 PAYER_UNREACHABLE as transient and retry. Never surface it to a front desk as though the patient has a problem.",
    "Log the code rather than the prose. When a flow stalls in production, the sequence of codes is what you diagnose it from.",
  ]}
/>

## The ones that are not what they look like

A short list of codes that reliably get misread:

<CostTable
  rows={[
    {
      where: "Identify",
      symptom: "MEMBER_NOT_FOUND",
      cause: "Usually the identifier was sent without its type, or with the wrong one. Genuine absence is the rarer case.",
    },
    {
      where: "Eligibility",
      symptom: "PAYER_UNREACHABLE",
      cause: "Transient, so retry it. The answer is about infrastructure and says nothing about eligibility.",
    },
    {
      where: "Consent",
      symptom: "CONSENT_SESSION_PENDING",
      cause: "The session is stale rather than busy. Reject it and create a new one, because retrying create will keep failing.",
    },
    {
      where: "Submit",
      symptom: "NEEDS_REVIEW",
      cause: "This is a warning rather than a blocker. Billing carries on, but nothing reaches submission until someone confirms it.",
    },
    {
      where: "Submit",
      symptom: "ALREADY_CLOSED",
      cause: "Nothing is broken; your state is simply behind. Treat it as success rather than opening a second visit.",
    },
  ]}
/>

---

## /rail/reference/Terminology-Concept-Maps

# Translating between vocabularies

  Your clinicians code a diagnosis once. Some payers want ICD-11, others are still on ICD-10, and
  what bridges those two facts is a concept map, not a column in your database.

## The situation this solves

A clinician records cholera. Your system stores `1A00`, the ICD-11 code, because that is the
vocabulary the rail codes diagnoses in. Then a claim goes to a payer whose adjudication engine only
understands ICD-10, where the same condition is `A00.9`.

There are three ways to handle that. Two of them go wrong later.

<Wire
  rows={[
    { call: "Store both codes", does: "Two columns, filled at capture time. It works until either vocabulary is revised, at which point your stored pairs disagree with the published crosswalk and nobody can say which is right.", keep: "don't" },
    { call: "Maintain your own mapping table", does: "A spreadsheet somebody owns. It is correct on the day it is written and quietly wrong after that. It is also the same work the terminology owner is already doing, done less well.", keep: "don't" },
    { call: "Store the primary code, translate on demand", does: "One code in your record. When a payer needs the other vocabulary, ask the service. The mapping stays owned by the people who curate it.", keep: "the ICD-11 code" },
  ]}
/>

  Store the vocabulary you captured in, and treat every translation as derived. A system that keeps
  the ICD-10 code as its primary representation, because that is what one payer wanted, has signed up
  for a migration nobody has scheduled, and it can no longer say what the clinician actually chose.

## What a concept map is

A concept map is a named, versioned set of rows with an owner. Each row says that this source code
corresponds to that target code, and how strong the correspondence is.

The strength is the part people skip, and it is what decides whether a translation is safe to apply
unattended.

<Wire
  rows={[
    { call: "equivalent", does: "The same thing. Safe to substitute without anyone looking.", keep: "use it" },
    { call: "narrower", does: "The source is more specific than the target. Translating loses detail, which is usually acceptable because the target still covers the case.", keep: "use it, know what was lost" },
    { call: "broader", does: "The source is more general than the target. Translating adds specificity nobody recorded, so surface this one rather than applying it silently.", keep: "flag it" },
    { call: "related", does: "Connected, but not a substitution. Not a translation you can bill on.", keep: "a human decides" },
    { call: "notrelated", does: "Explicitly not a match. Recorded so nobody proposes it again.", keep: "do not use" },
    { call: "nomap", does: "A deliberate statement that this code has no target in this map, with a reason. Somebody looked and decided. See the warning below.", keep: "the reason" },
    { call: "unmapped", does: "Nobody has decided yet. The work has not been done, which is not the same as a conclusion.", keep: "chase it" },
  ]}
/>

`wider` and `unmatched` are accepted spellings of `broader` and `notrelated`, kept for callers written
against the older vocabulary. Send the current names.

  Translating on a `broader` row means the code you send is more specific than the one your clinician
  chose. That can change what a payer thinks was treated. Where a map row is `broader`, put the
  translation in front of a person before it goes on a claim. Where volume makes that impossible, at
  least log that it happened, so a query about the claim can be answered.

## Doing it

<Wireframe
  title="Diagnosis"
  actor="Clinician"
  rows={[
    [{ label: "Primary diagnosis", from: "1A00 · Cholera", kind: "field", tone: "positive", span: 4, note: "ICD-11. The only code stored on the encounter." }],
    [{ label: "Payer requires ICD-10", from: "A00.9 · Cholera, unspecified", kind: "text", span: 3, note: "Resolved by the crosswalk at submission. Equivalence: broader" },
     { label: "equivalent?", from: "broader", tone: "attention", span: 1, note: "Less specific than what was recorded, so the screen shows it" }],
    [{ label: "Submit claim", kind: "action", span: 4 }],
  ]}
  caption="The clinician never picks an ICD-10 code and never sees a second dropdown. The screen surfaces only what a person should judge, which is that this particular translation is not an exact correspondence."
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    participant H as Your HMIS
    participant T as Terminology service
    participant P as Payer

    Note over H,T: Once, at configuration time
    H->>T: GET /concept-maps/?source_code_system=..&target_code_system=..
    T-->>H: The maps that exist, with their short codes
    Note over H: Put the short code in configuration.<br/>Do not resolve it per claim.

    Note over H,T: Per code, at submission
    H->>T: GET /concept-maps/{short code}/$translate/?code=1A00&version=serving
    T-->>H: Parameters { result: true, match: [{ equivalence, concept }] }
    Note over H: Read the equivalence, not only the code.
    H->>P: Claim, carrying the target code
`} />

<Mermaid chart={`flowchart TD
    A["A payer needs another vocabulary"] --> B["GET /$translate/?code=..."]
    B --> C{"result true?"}
    C -- Yes --> D{"equivalence?"}
    D -- "equivalent / narrower" --> E["Use the target code"]
    D -- broader --> F["Use it, but log it,<br/>or show a person"]
    D -- "related / notrelated" --> G["Not a billable translation.<br/>A human decides."]
    C -- No --> H["GET /entries/?search=code<br/>why is there no match?"]
    H --> I{"A row with no_map true?"}
    I -- Yes --> J["Deliberate: this code has<br/>no target, and there is a reason.<br/>Do not chase it."]
    I -- No --> K["Nobody has mapped it yet.<br/>Raise it with the terminology owner."]
`} />

## Find the map once

Maps are configuration rather than runtime state. Resolve the map when you set the integration up
and put its short code in your configuration. Resolving it per claim adds a round trip to every
submission for an answer that changes about once a year.

Use the short code rather than the numeric id. `ICD11-TO-ICD10` says what it is in a code review and
means the same thing in every environment. `7` says nothing and is deployment specific.

<TryIt
  title="Which concept maps exist?"
  path="/concept-maps/?page_size=20"
  anonymous
  keep="the map id, and its canonical_url"
>
  Published maps are listed without a credential. Filter with `source_code_system=` and
  `target_code_system=`, which take numeric ids from the catalogue because they are filters rather
  than path lookups, or resolve one straight from the `canonical_url` a FHIR payload carries.
  More than one map can share a canonical url, so this can legitimately return several rows and the
  caller picks. Keep the `short_code` from the row you pick, not the id.
</TryIt>

## Translate a code

<TryIt
  title="Translate one code"
  method="GET"
  path="/concept-maps/ICD11-TO-ICD10/$translate/?code=1A00&version=serving"
  keep="the target code, and its equivalence"
>
  Edit the short code and the code. Every concept map route takes the map's `short_code` in place of
  its numeric id, so a request stays readable. The answer is a FHIR `Parameters` resource: `result`, then one
  `match` per target, each carrying an `equivalence` and the target `Coding`. Read both, because a
  target code without its equivalence is half the answer.
</TryIt>

<ApiRef method="GET" path="/concept-maps/{short code}/$translate/?code={code}" to="/terminology-api/concept-maps" keep="the target code">
  Full parameters, response shape and the failure cases in the reference.
</ApiRef>

Omitting `code` returns a `400` carrying a FHIR `OperationOutcome` rather than a plain error body,
which is worth knowing if your client only parses one error shape.

## When `result: false` means two things

`$translate` deliberately excludes rows declared `no_map`, and rows whose target is blank. They are
not translations, so they cannot be returned as matches.

The consequence is that `result: false` covers two completely different situations, and this
operation cannot tell you which one you are in:

<Wire
  rows={[
    { call: "Nobody has mapped this code", does: "Missing work. Raise it, because a code your clinicians use that has no crosswalk row will fail at every payer on the other vocabulary.", keep: "escalate" },
    { call: "Somebody decided it maps to nothing", does: "Completed work, with a recorded reason. There is no target and there is not going to be one, so chasing it only wastes an afternoon.", keep: "the reason" },
  ]}
/>

To tell them apart, read the rows:

<TryIt
  title="Why is there no translation?"
  path="/concept-maps/ICD11-TO-ICD10/entries/?search=1A00"
  keep="no_map, no_map_reason, equivalence"
>
  The entry listing shows what `$translate` hides. A row with `no_map: true` carries a
  `no_map_reason`, which is a decision rather than a gap. No row at all means nobody has looked yet.
  You can also filter the whole map by `equivalence=unmapped` to see how much work is outstanding
  before you depend on it.
</TryIt>

## Loading a whole crosswalk instead

Per-code translation is right for a claim. It is wrong for a bulk reconciliation of forty thousand
historical encounters, because that is forty thousand round trips.

<ApiRef method="GET" path="/concept-maps/{short code}/concept-map.json" to="/terminology-api/concept-maps" keep="the bundle">
  The whole map as a FHIR R4 ConceptMap resource, for loading into your own terminology client.
</ApiRef>

If you take this route, cache the map against the version you fetched and re-check it on a schedule.
A crosswalk copied into your database drifts in exactly the way this page opened by warning about.
The difference is that you now own the drift deliberately, with a version recorded, rather than by
accident.

  A concept map's version ordering is inferred from row creation time, because `ConceptMapVersion`
  lacks the `sequence` ordinal its code system counterpart has. Without that ordinal there is nothing
  to reconstruct past membership from, so a `?version=` read of `$translate` degrades to translating
  against the current rows rather than the rows as they stood at that release.

  It still answers, but the answer is today's rather than a frozen historical translation. If you may
  ever have to defend what a code translated to, record the target and the equivalence at the time you
  used them. This gap is specific to concept maps. Code systems and value sets do freeze, so the same
  caveat does not apply to `/concepts/` or an expansion.

## What breaks here

<CostTable
  rows={[
    {
      where: "Submission to one payer only",
      symptom: "\"Claims to this payer reject on the diagnosis, everyone else is fine\"",
      cause:
        "Either no translation is happening for the payer on the other vocabulary, or the map id in configuration points at the wrong pair of systems.",
    },
    {
      where: "A handful of codes, repeatedly",
      symptom: "\"These five diagnoses always fail and we keep re-raising them\"",
      cause:
        "They are almost certainly `no_map` rows with a recorded reason. Read /entries/ once and stop chasing them.",
    },
    {
      where: "An audit or a payer query",
      symptom: "\"The claim says one thing and the clinical record says another\"",
      cause:
        "A broader translation applied silently. Log the equivalence alongside the translated code so you can explain the difference.",
    },
    {
      where: "A bulk reconciliation",
      symptom: "\"The job takes nine hours and gets throttled\"",
      cause:
        "One $translate per row. Fetch the map once as FHIR and translate locally.",
    },
    {
      where: "Months after a vocabulary revision",
      symptom: "\"Our stored ICD-10 codes no longer match the crosswalk\"",
      cause:
        "The second code was stored at capture time. Store the primary code and derive the other one when it is needed.",
    },
  ]}
/>

**Next:** [Getting the data you need](/rail/reference/Terminology-Getting-Data) ·
[Validating a code](/rail/reference/Terminology-Validating-Codes) ·
[Pinning to a release](/rail/reference/Terminology-Pinning-Versions)

---

## /rail/reference/Terminology-Getting-Data

# Getting the data you need

  The same terminology comes out in four shapes. One question picks between them: is a program
  reading this, a FHIR client, or a person?

Wherever this documentation says "from a list you fetched", this is the page it means.

## Address artefacts by their code, not their id

Before any of the calls below, note that every code system, value set and concept map is addressable
by its short code as well as by its numeric id. `/code-systems/IDENTIFIER-TYPES/` and
`/code-systems/1251/` resolve to the same row, and so does every action hanging off it: expansions,
FHIR exports, `$validate-code`, `$translate`.

Use the code. An id is deployment specific, so the number that identifies a vocabulary in the
development environment is not the number in production. A published short code is the same
everywhere and readable in a diff.

<Wire
  rows={[
    { call: "Resolution is pk-first", does: "A value that looks numeric is tried as an id first and then falls through to the code column, so an all-digits short code is still reachable. After an exact miss the lookup ignores case, because a code derived from a canonical url takes that url's casing and nobody types it back the same way.", keep: "the short code" },
    { call: "One ambiguity, resolved predictably", does: "A short code identical to some other row's numeric id resolves to the id. That is the documented rule, but it is also a reason not to mint numeric-looking short codes.", keep: "avoid numeric codes" },
    { call: "Concepts are the exception", does: "A concept code is unique only within its system, so concept routes take a numeric id. Resolve it from GET /concepts/?system=<short code> and store it beside the code.", keep: "the concept id" },
    { call: "Filters still take ids", does: "?code_system=, ?source_code_system= and ?target_code_system= are filters rather than path lookups, so they take numeric ids. ?system= is the code-based alternative and accepts a short code or a canonical url.", keep: "?system=" },
  ]}
/>

## Pick the shape first

<Wire
  rows={[
    { call: "Paged JSON", does: "A running integration. Cheap, cacheable, pinned to a version, and the only one of the four you should call while a patient is waiting.", keep: "GET /concepts/" },
    { call: "FHIR R4", does: "Loading a vocabulary into a terminology client that speaks FHIR, or handing a payer something in a standard shape. One request, one whole resource, with a size bound on it.", keep: "GET /code-systems/{short code}/export/" },
    { call: "CSV or Excel", does: "A person. Reviewing a vocabulary, seeding a mapping exercise, sending a list to somebody who will open it in a spreadsheet. It is asynchronous: you ask, then poll, then download.", keep: "POST /release-jobs/" },
    { call: "Codes only", does: "A bare list, when all you need is the enumeration and nothing about it. Generating a constant, checking membership offline.", keep: "format: CODES" },
  ]}
/>

One mistake is worth naming up front. A spreadsheet is not an integration. Downloading an Excel file
on a schedule and importing it into your own tables reproduces, by hand, what the paged JSON call
already does correctly, and it loses the version pinning that makes the JSON safe.

## For a program: paged JSON

It is one call, and one parameter on it does the real work.

<TryIt
  title="Fetch a coded list"
  path="/concepts/?system=IDENTIFIER-TYPES&version=serving&page_size=50"
  keep="code, display, next"
>
  Swap `system` for any short code from the catalogue. It accepts the short code or the canonical
  url, and `code_system=` takes the numeric id instead. `version=serving` is the parameter that
  matters, because it pins the read to the release the owner is serving. Look at `count` and `next`
  in the answer before you decide your sync is finished.
</TryIt>

<Wire
  rows={[
    { call: "?system= or ?code_system=", does: "Short code or canonical url in the first; numeric id in the second. Use whichever identity you actually hold rather than translating between them.", keep: "the short code" },
    { call: "?version=serving", does: "The release the author or regulator is serving. Without it you get whatever that artefact defaults to: the working copy including drafts if it is unpinned, the pinned version if it is not. Send it and the answer stops depending on somebody else's setting.", keep: "serving" },
    { call: "?page_size= and next", does: "Paging. Follow next rather than computing page numbers; a sync that reads page one ships a fraction of a vocabulary and looks like it worked.", keep: "next" },
    { call: "?parent_code= and ?root_only=", does: "Walking a hierarchy one level at a time, rather than pulling forty thousand rows to render a dropdown.", keep: "parent_code" },
    { call: "?concept_class= and ?status=", does: "Separating selectable concepts from grouping nodes, and active codes from withdrawn ones.", keep: "concept_class" },
  ]}
/>

Where the vocabulary is a tree rather than a list, [walking it](/rail/reference/Terminology-Walking-The-Tree)
is its own technique and worth reading before you fetch anything large.

## For a FHIR client: the resource itself

<TryIt
  title="One code system as FHIR"
  path="/code-systems/IDENTIFIER-TYPES/export/?format=fhir&version=serving"
  keep="the CodeSystem resource"
>
  The FHIR R4 CodeSystem, built and returned in the response. `?format=fhir` selects the
  `application/fhir+json` media type; without it you get ordinary JSON with the same body.
</TryIt>

Three things this endpoint does that are worth knowing before you point a client at it.

<Wire
  rows={[
    { call: "It is bounded", does: "The full payload holds every concept in memory before responding, so a system above the inline limit answers 413, and the message names the release job to use instead. The 413 is a real answer rather than a sign that the service is down.", keep: "413 means go async" },
    { call: "?_summary=true", does: "The header without the codes, at the same cost whether the system holds ten concepts or forty thousand. The call to use when you only need identity and metadata.", keep: "content: not-present" },
    { call: "A closed system has no FHIR form", does: "A provider rate agreement answers 406. It is not a public vocabulary and there is no representation to serve.", keep: "406 is deliberate" },
  ]}
/>

The same representation is available through the ordinary detail read as `?view=fhir`. Both routes
call one method and share the same refusals, so they cannot drift apart.

Value sets have the same pair: `/expansion/` for the paged member list, and the FHIR form for a
client that wants the resource.

<ApiRef method="GET" path="/value-sets/{short code}/expansion/?version=serving" to="/terminology-api/value-sets" keep="codes">
  The member list of a value set. Identical response shape whether the expansion was precomputed or
  resolved on the spot, so you never branch on which happened.
</ApiRef>

## For a person: CSV, Excel, or a bare code list

This is a release job: you ask, you poll, you download. Three calls. It is asynchronous because a
full export of a large vocabulary takes too long to hold a request open for.

<Wireframe
  title="Export a code system"
  actor="Terminology reviewer"
  rows={[
    [{ label: "Artefact", from: "codesystem · SHA-INTERVENTIONS", kind: "field", span: 2 },
     { label: "Version", from: "v1.4.0 (serving)", kind: "field", span: 2, note: "A released version, not the working copy" }],
    [{ label: "Format", from: "XLSX", kind: "field", swatch: 1, span: 2, note: "FHIR · CSV · XLSX · CODES" },
     { label: "Mode", from: "SNAPSHOT", kind: "field", swatch: 2, span: 2, note: "FULL · SNAPSHOT · DELTA" }],
    [{ label: "Include withdrawn concepts", from: "include_inactive: false", kind: "text", span: 4, note: "Off for a review list; on when the file has to explain historical records" }],
    [{ label: "Preview first", kind: "action", span: 2, note: "Row counts and samples, nothing stored" },
     { label: "Generate", kind: "action", span: 2 }],
  ]}
  caption="Format decides who can open the file. Mode decides what is in it, and mode is the choice people get wrong, because FULL and SNAPSHOT differ exactly when a concept has been withdrawn since the release."
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    participant Y as You
    participant T as Terminology service

    Y->>T: POST /release-jobs/preview/ (same body as create)
    T-->>Y: Row counts + sample rows, nothing stored
    Note over Y: Confirm this is the dataset you meant.

    Y->>T: POST /release-jobs/ { artifact, version_id, mode, format }
    T-->>Y: 201 { id, status: "queued" }

    loop until COMPLETED
      Y->>T: GET /release-jobs/{job id}/
      T-->>Y: { status, row_count }
      Note over Y,T: Polling needs no credential.
    end

    Y->>T: GET /release-jobs/{job id}/download/
    T-->>Y: 302 to the current presigned URL
    Note over Y: Follow the redirect.<br/>Never store the URL it points at.
`} />

<Mermaid chart={`flowchart TD
    A["Somebody needs a file"] --> B{"Who opens it?"}
    B -- "A person, in a spreadsheet" --> C["format: XLSX or CSV"]
    B -- "A FHIR client" --> D["format: FHIR"]
    B -- "Code generation" --> E["format: CODES"]
    C --> F{"First copy, or an update?"}
    D --> F
    E --> F
    F -- "First copy" --> G["mode: FULL or SNAPSHOT"]
    F -- "Update to an existing copy" --> H["mode: DELTA<br/>+ base_version_id"]
    G --> I["POST /release-jobs/preview/<br/>check before you queue"]
    H --> I
    I --> J["POST /release-jobs/"]
    J --> K["Poll GET /release-jobs/{job id}/"]
    K --> L{"status COMPLETED?"}
    L -- No --> K
    L -- Yes --> M["GET /release-jobs/{job id}/download/"]
`} />

### The two choices that shape the file

<Wire
  rows={[
    { call: "format: FHIR", does: "FHIR R4 JSON. For a machine that speaks it.", keep: "-" },
    { call: "format: CSV", does: "One row per concept, openable anywhere, diffable in git.", keep: "-" },
    { call: "format: XLSX", does: "Excel. What to send someone who will annotate it and send it back.", keep: "-" },
    { call: "format: CODES", does: "The bare enumeration, nothing else. For generating a constant.", keep: "-" },
  ]}
/>

<Wire
  rows={[
    { call: "mode: FULL", does: "Everything belonging to that version, exactly as it was frozen. This is the defensible choice, because a released version never changes and the export can be reproduced.", keep: "version_id" },
    { call: "mode: SNAPSHOT", does: "Membership as it stands now, with include_inactive deciding whether withdrawn concepts come too. Right for a picker list and wrong for an audit, because what it returns depends on when you asked.", keep: "include_inactive" },
    { call: "mode: DELTA", does: "Only what changed against base_version_id. Use it to update a local copy incrementally instead of re-downloading the whole thing. On a large vocabulary that turns an hour into a minute.", keep: "base_version_id" },
  ]}
/>

<TryIt
  title="Poll a release job"
  path="/release-jobs/1/"
  anonymous
  keep="status, row_count"
>
  Polling is public, so this one runs with no credential at all. Edit the id. Creating a job and
  downloading the file both need a token; reading the job status does not.
</TryIt>

<ApiRef method="POST" path="/release-jobs/" to="/terminology-api/getting-the-data-out" keep="id">
  Create the job. The full body, both required-field failures, and the mode and format enumerations
  are in the reference.
</ApiRef>

### Five things that will otherwise cost you an afternoon

<Wire
  rows={[
    { call: "This is the one call that needs numeric ids", does: "artifact_id and version_id are both integers here, so resolve them first: GET /code-systems/<short code>/ gives you the artefact id, and /versions/ gives you the version ids with is_serving marking the one serving resolves to. Everywhere else on this page takes a short code.", keep: "both ids" },
    { call: "version_id is required", does: "Omit it and the create answers 400 with {\"version_id\": [\"This field is required.\"]}. base_version_id is required the same way when mode is DELTA.", keep: "version_id" },
    { call: "Do not store output_file_url", does: "It is a presigned link regenerated on every poll, so the copy you saved is not the one that works. Hit /download/ instead, which always redirects to the live one.", keep: "the job id" },
    { call: "A 202 is not a file", does: "The older /bulk/export/ endpoints queue a CSV and answer 202 with no job id at all, so there is nothing to poll and no link to follow. Use a release job whenever you need the file back.", keep: "use release jobs" },
    { call: "Preview before you queue", does: "/release-jobs/preview/ takes the same body and answers with counts and sample rows, storing nothing. It is the cheapest way to find out that your DELTA base was the wrong version.", keep: "row_count" },
  ]}
/>

## Keeping a local copy honest

<BuildSequence
  steps={[
    { do: "Sync on a schedule, never during a visit", detail: "A pick-list fetched while a patient waits can also fail while a patient waits." },
    { do: "Read ?version=serving, and record what it resolved to", detail: "Log the version with every coded value you store. When a code stops being accepted, that log lets you answer why instead of guessing." },
    { do: "Update with DELTA where the vocabulary is large", detail: "Re-downloading forty thousand concepts to learn that three changed is a habit that eventually gets scheduled hourly by mistake." },
    { do: "Poll /staleness/ for value sets rather than re-expanding", detail: "stale_count: 0 means your cached expansion still reflects its sources. Re-expansion is an authoring action and it is expensive." },
    { do: "Put it behind one interface of your own", detail: "A single getValueSet(system) in your code means a list moving from a bespoke endpoint to the generic one is a one-file change rather than a migration." },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "A sync that has always worked",
      symptom: "\"We are missing codes that are definitely published\"",
      cause:
        "Paging. The first page came back, looked right, and nobody followed next.",
    },
    {
      where: "A FHIR export of a large system",
      symptom: "\"It returns 413 and we assumed the service was down\"",
      cause:
        "It is the documented bound, and the message names the alternative. Use ?_summary=true for the header or a release job for the content.",
    },
    {
      where: "A download link shared with a colleague",
      symptom: "\"The link expired / the link 403s for them\"",
      cause:
        "A stored output_file_url. Share the job id and let them hit /download/.",
    },
    {
      where: "An export used as evidence",
      symptom: "\"Two people exported the same list and got different files\"",
      cause:
        "SNAPSHOT mode, taken at different times. FULL against a version_id is reproducible; SNAPSHOT is deliberately not.",
    },
    {
      where: "A scheduled spreadsheet import",
      symptom: "\"Our list drifts from the published one\"",
      cause:
        "A spreadsheet used as an integration. The paged JSON call exists precisely so this is not necessary.",
    },
  ]}
/>

**Next:** [Pinning to a release](/rail/reference/Terminology-Pinning-Versions) ·
[Translating between vocabularies](/rail/reference/Terminology-Concept-Maps) ·
[The whole surface](/rail/reference/Terminology-Service)

---

## /rail/reference/Terminology-Pinning-Versions

# Pinning to a release

  Terminology changes upstream, on somebody else's schedule, without a deployment on your side.
  The version you read is the one control you have over that, and the default is the wrong
  one.

## The default reads drafts

Omit the version and, in the usual case, you read the working copy. That is correct when you are
authoring terminology, since an editor needs to see the change they just made. It is wrong in every
integration, because a draft concept that nobody approved can reach a patient-facing screen, be
picked, and be submitted on a claim.

"In the usual case" is doing real work in that sentence. An unversioned read serves the working copy
only while the artefact is unpinned; under a manual pin it already serves that frozen version without
being asked. So omitting the version leaves you at the mercy of somebody else's pin setting. The
same call returns live rows on one vocabulary and frozen content on another, and nothing in your
code says which. Send `serving` and the question stops mattering.

Three ways to read the same call, in the order you should reach for them:

<Wire
  rows={[
    { call: "?version=serving", does: "The version the artefact currently resolves to: the owner's pin if there is one, otherwise the newest released version effective today. A frozen read without having to look up a number first. This is what an integration sends on every runtime call.", keep: "the version it resolved to" },
    { call: "?version=v1.2.0", does: "Exactly that release, by its version_id (or its numeric id). Only released versions are honoured. A pinned read like this is cacheable indefinitely.", keep: "the version_id" },
    { call: "?version=draft", does: "The pending draft, for reviewers. Gated on the reviewer permission, and not something an integration sends.", keep: "—" },
    { call: "omitted", does: "Depends on the artefact: the working copy including drafts while it is unpinned, or the pinned version if somebody has set one. Right when authoring terminology, wrong when integrating with it, not because it is always live but because you cannot tell.", keep: "—" },
  ]}
/>

  `serving` means the version the owner is serving. It is not the newest edit, and it is not
  always the newest release either, as the next section shows. Approval is a deliberate act by a
  terminology author or a regulator, and sending `serving` means you follow that decision rather
  than whatever was typed this morning.

## What `serving` actually resolves to

"Latest" is the wrong mental model here, so this part is worth being precise about. Every versioned
artefact carries a `pin_mode`, and that decides the answer:

<Wire
  rows={[
    { call: "pin_mode: MANUAL", does: "The owner has pinned a specific release. serving resolves to exactly that version and stays there, because a newer release does not move it. This is how a regulator holds a vocabulary steady while a later version is prepared, or holds consumers on a known-good release after a problem.", keep: "pinned_version" },
    { call: "pin_mode: AUTO_LATEST", does: "No pin. serving resolves to the newest released version whose effective date has arrived. This is the common case, and it is what lets a new approved code reach your pickers without a deployment on your side.", keep: "the newest release" },
  ]}
/>

Two things follow from that, and both are intended behaviour rather than quirks.

A future-dated release is not served early. Effective dates are wall-clock dates set by an author,
so a version dated next Monday is invisible to `serving` until Monday, with no coordination needed
on your side. "Today" means today in the deployment's own timezone rather than UTC. That is on
purpose: comparing against UTC would leave a release dated today unservable until three in the
morning local time.

A pin that can no longer be served does not break the read. If a pinned version is retired, the
read falls through to the newest release and says so: the artefact carries a `pin_warning`, and the
version ladder shows the state. You get terminology back rather than an error, along with a signal
that somebody's pin needs attention.

### Reading which version you are on

<TryIt
  title="The version ladder and the pin"
  path="/code-systems/IDENTIFIER-TYPES/versions/"
  keep="version_id, is_serving, pin_mode"
>
  Start with `serving` at the top of the response. It is the `version_id` that `?version=serving`
  resolves to, or `null` when nothing is servable. Beside it, `pin_mode`, `pinned_version` and
  `pin_warning` say whether that answer was somebody's deliberate choice or simply the newest release.
  Each row then carries `is_serving` and `is_head_draft`, so you never need a second call to work out
  which is which.
</TryIt>

## Which to send where

`serving` and a fixed version answer different questions, and most integrations need both, in
different places.

<Wire
  rows={[
    { call: "Send serving on every runtime read", does: "Pickers, validation, expansions. You want the terminology the owner is standing behind, and you want a newly approved code to appear without a release on your side.", keep: "serving" },
    { call: "Store the resolved version with the code", does: "When you store a coded value, store which version you read it at. Interpreting a two-year-old claim means reading the vocabulary as it stood then, and a fixed ?version= is how you do that.", keep: "version_id, beside the code" },
    { call: "Send a fixed version when a run must be reproducible", does: "A migration, a reconciliation, a regulatory extract. Pinning explicitly means running it again next month gives the same answer. The read is also cacheable indefinitely, which a long job notices.", keep: "the version_id" },
  ]}
/>

That second habit is what makes an old record defensible. Without it, a code that has since been
withdrawn looks like a data error rather than a code that was correct on the day.

  A code system release that predates the service's content-versioning backfill carries no internal
  ordinal, so there is nothing to read frozen content at. Rather than fail, the read serves the live
  working copy, at `200`, with nothing in the body or the headers to say it happened. A response
  in this state is indistinguishable from genuinely frozen content.

  So if your reasoning is "`serving`, therefore frozen, therefore safe to cache forever", this is the
  case that breaks it, and you cannot detect it on the response.

  What you can check is the artefact. A ladder row carries a `sequence`, an internal ordinal you
  should never render but which tells you what you need here: for a code system, a released version
  with `sequence: null` has no frozen content to serve. Check `/versions/` before caching a pinned
  read for a long time, and treat a null-ordinal release as live.

  Build the check rather than waiting for the condition to disappear. A missing ordinal on an old
  release is a supported state in the service's own schema, not a data defect somebody is about to
  clean up, so these releases will keep behaving this way.

  One boundary, so the check is not misapplied: value set and concept map versions have no ordinal at
  all, so `sequence` is always `null` on their rows and means nothing there. This test is only
  meaningful for code systems.

  `version_id` is a display label. Its numbering is not monotonic across the paths a version can
  be minted through, so `v1.10.0` is not reliably newer than `v1.9.0` and sorting a ladder by it will
  eventually put the wrong release at the top. The service orders by an internal `sequence` where the
  model has one and by creation time otherwise; take the order as given, and use `is_serving` rather
  than "the first row" to decide what is live.

  A `?version=` read of a released version answers `Cache-Control: immutable` with a one-year
  lifetime, because frozen content cannot change. An unversioned read answers `no-cache`, because its
  body flips the moment something is released and nothing in the rows you would cache on has changed.
  If your caching layer treats those two the same, it is serving stale terminology on one of them.

## Seeing what changed

<ApiRef method="GET" path="/code-systems/{system}/changed/" to="/terminology-api/versioned-reads">
  The working copy against the serving version. A modified row carries both the before and after
  objects, so you can show what actually changed rather than that something did.
</ApiRef>

<Wireframe
  title="Terminology sync · pending release"
  actor="Integration owner"
  rows={[
    [{ label: "INTERVENTIONS", from: "cached at version 7", kind: "text", span: 2 },
     { label: "Version 8 released", note: "2 days ago", tone: "attention", span: 2 }],
    [{ label: "Added", from: "3 concepts", tone: "positive", span: 2 },
     { label: "Withdrawn", from: "1 concept", tone: "negative", span: 2 }],
    [{ label: "INT-CARD-ECHO-TOE withdrawn", note: "In use on 4 unsubmitted claims, so these need attention before the sync", kind: "text", span: 4 }],
    [{ label: "Sync to version 8", kind: "action", span: 2 },
     { label: "Stay on 7", kind: "action", span: 2 }],
  ]}
  caption="The withdrawn concept is the row that matters. A sync that silently replaced the cache would have left four claims carrying a code the payer no longer accepts, and nothing would have said so until submission."
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    participant J as Your sync job
    participant T as Terminology service
    participant D as Your cache

    J->>T: GET /code-systems/{system}/versions/
    T-->>J: The ladder: releases, and which one is serving
    J->>D: Which version are we holding?
    D-->>J: 7
    Note over J: 8 exists. Do not replace yet.

    J->>T: GET /concepts/?system={system}&version=8
    T-->>J: The frozen membership of release 8
    Note over J: Diff against 7.<br/>Withdrawn codes are the interesting half.
    J->>D: Store 8 alongside 7, then switch
    Note over J,D: Anything unsubmitted that references<br/>a withdrawn code is flagged, not rewritten.
`} />

<Mermaid chart={`flowchart TD
    A["Scheduled sync"] --> B["GET /versions/"]
    B --> C{"A newer release than<br/>the one cached?"}
    C -- No --> D["Nothing to do"]
    C -- Yes --> E["Fetch ?version=&lt;version_id&gt;<br/>for the new release"]
    E --> F["Diff against the cached version"]
    F --> G{"Any concepts withdrawn?"}
    G -- No --> H["Switch the cache over"]
    G -- Yes --> I["Find unsubmitted records<br/>using a withdrawn code"]
    I --> J{"Any found?"}
    J -- No --> H
    J -- Yes --> K["Flag them for a human.<br/>Do not rewrite a clinical code<br/>automatically."]
    K --> H
    H --> L["Log the version you switched to,<br/>and when"]
`} />

## Withdrawn is not deleted

A withdrawn code still comes back, marked inactive, and this is deliberate: a record from last
year that references it still has to render. Two rules follow, and they pull in opposite
directions:

<Wire
  rows={[
    { call: "Filter for pickers", does: "is_active: true and status PUBLISHED is what belongs in a dropdown. Offering a withdrawn code produces a rejection nobody can explain to the operator who picked it.", keep: "is_active" },
    { call: "Do not filter for history", does: "When interpreting stored data, read everything. A filter applied here makes old records render as blanks, which looks like data loss.", keep: "the full set" },
  ]}
/>

One list, two reads. If your terminology layer exposes a single `getValueSet(system)` that always
filters, the history path has no way to ask for what it needs.

## Building so a release is not an incident

<BuildSequence
  steps={[
    {
      do: "Send version=serving on every runtime read",
      detail:
        "In one place, in your HTTP client for the terminology service, so no call site can forget it. A missing version parameter should be impossible rather than caught in review.",
    },
    {
      do: "Store the version with every code you store",
      detail:
        "One extra column. It is the difference between explaining an old claim and guessing about it.",
    },
    {
      do: "Diff before you switch the cache over",
      detail:
        "Read /versions/, fetch the new release by its version_id, and compare. The withdrawn half of the diff is what needs a human.",
    },
    {
      do: "Never auto-rewrite a clinical code",
      detail:
        "A withdrawn diagnosis on an unsubmitted claim is a clinical decision to revisit, not a mapping to apply. Flag it and let somebody look.",
    },
    {
      do: "Log the version you switched to, and when",
      detail:
        "When a coded value stops being accepted, the first question is which version you were reading and since when. Make that answerable in one query.",
    },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "A picker, intermittently",
      symptom: "\"A code appeared that nobody approved\"",
      cause:
        "The version parameter was omitted, so the read included drafts. Send serving.",
    },
    {
      where: "Submission, after a quiet upstream release",
      symptom: "\"Claims started rejecting on Tuesday and we changed nothing\"",
      cause:
        "That reading is usually right. You changed nothing, and the vocabulary did. Read /versions/ for the release and its effective date, then diff it.",
    },
    {
      where: "Reporting on old claims",
      symptom: "\"Historical records show blanks where a diagnosis used to be\"",
      cause:
        "The history path is filtering on is_active, so withdrawn codes resolve to nothing. Filter for pickers only.",
    },
    {
      where: "An audit",
      symptom: "\"We cannot say which version of the vocabulary this claim was coded against\"",
      cause:
        "The version was never stored beside the code. It cannot be reconstructed afterwards.",
    },
    {
      where: "A sync job",
      symptom: "\"The cache silently replaced itself and four claims broke\"",
      cause:
        "A sync that fetches and overwrites, with no diff step. The withdrawn concepts are the ones that need to be seen before the switch.",
    },
  ]}
/>

**Next:** [Getting the data you need](/rail/reference/Terminology-Getting-Data) ·
[Validating a code](/rail/reference/Terminology-Validating-Codes) · or the whole surface at
[the terminology service](/rail/reference/Terminology-Service)

---

## /rail/reference/Terminology-Service

# The whole surface

  Every coded thing on the rail resolves here: what a code means, whether it is still valid, what it
  belongs to, what it maps to, and what it costs. One service answers all seven kinds of question.

This page lists every operation, grouped by the question it answers, with a link into
[the Terminology API reference](/terminology-api) where each one can be read in full. Four of the
groups are taught in their own right, so if you have a task rather than a survey in mind, start
there.

- [Fetching a coded list](/rail/reference/Value-Sets), for populating a dropdown, syncing on a
  schedule, or exporting a list as a spreadsheet for a human to review.
- [Walking a concept tree](/rail/reference/Terminology-Walking-The-Tree), because large vocabularies
  are hierarchies and the list you are handed often starts partway down one.
- [Validating a code](/rail/reference/Terminology-Validating-Codes), checking a code at the
  boundary where it enters your system rather than at submission.
- [Pinning to a release](/rail/reference/Terminology-Pinning-Versions), covering what
  `version=serving` resolves to and how to stop an upstream vocabulary change from becoming an
  incident on your side.
- [Translating between vocabularies](/rail/reference/Terminology-Concept-Maps), for coding a
  diagnosis once when one payer wants ICD-11 and another is still on ICD-10.
- [Getting the data you need](/rail/reference/Terminology-Getting-Data), covering JSON, FHIR, CSV,
  Excel or a bare code list, in and out, and which shape to pick.

  Authentication is a token rather than a header. The service reads the realm from the token itself,
  so there is no variant or tenant header to guess at. What a call returns is scoped to the
  organisation that token belongs to.

  Anonymous is a real access level rather than a broken one. Discovery and search answer without any
  credential, and an unauthenticated caller sees only what is published publicly. A list that comes
  back emptier than you expected is usually a question of scope rather than absence.

## Discovery: what exists, and who you are

[Open the group in the reference →](/terminology-api/discovery)

<Wire
  rows={[
    { call: "GET /metadata", does: "What this server declares it supports. Make it the first call when wiring any FHIR terminology client.", keep: "the capability statement" },
    { call: "GET /orgs/current/", does: "Echoes the active organisation for this token. Run it the moment a list comes back emptier than expected, because the cause is almost always scope.", keep: "the active org" },
    { call: "GET /orgs/accessible/", does: "Every organisation this token can read, and how to switch between them.", keep: "org codes" },
    { call: "GET /code-systems/", does: "The catalogue. Authenticated callers see their organisation's systems; anonymous callers see only public ones.", keep: "short_code, id" },
    { call: "GET /code-systems/{system}/", does: "Detail for one system. Accepts either the numeric id or the short code, case-insensitively.", keep: "canonical url" },
    { call: "GET /code-systems/{system}/versions/", does: "The version ladder plus the pin: every version newest-first flagged is_serving, alongside pin_mode and pinned_version. This is how you learn what ?version=serving resolves to.", keep: "version_id, is_serving, pin_mode" },
    { call: "GET /code-systems/{system}/used-by/", does: "Which value sets and concept maps bind to this system. Check it before assuming a system can be retired.", keep: "—" },
  ]}
/>

## Concepts: reading one, and walking the tree

[Open the group in the reference →](/terminology-api/concepts) · taught in [Walking a concept tree](/rail/reference/Terminology-Walking-The-Tree)

<Wire
  rows={[
    { call: "GET /concepts/?system=", does: "The membership of a system, paged. It is version-aware, so ?version=serving pins to the release the owner is serving, and a version_id reads exactly what was frozen there.", keep: "code, display" },
    { call: "GET /concepts/{id}/", does: "One concept, with the identity a detail page needs: uri, owning system, and the version it was introduced in.", keep: "uri" },
    { call: "GET /concepts/roots/?system=", does: "The top of the tree. Start here for lazy rendering, then walk children.", keep: "root codes" },
    { call: "GET /concepts/{id}/children/ · /parents/", does: "One level in either direction.", keep: "—" },
    { call: "GET /concepts/{id}/descendants/ · /ancestors/", does: "Transitive, served from a closure table rather than computed by you.", keep: "—" },
    { call: "GET /concepts/{id}/value-sets/", does: "Reverse membership, meaning which value sets expand to include this concept.", keep: "—" },
    { call: "GET /concept-revisions/?concept=", does: "Append-only revisions for one concept, each carrying the full child collections, so a revision is a faithful 'before' for a diff.", keep: "—" },
  ]}
/>

  Ancestors and descendants are served from a closure table. Fetching children repeatedly and
  assembling the tree in the client is slower, and it drifts the moment the vocabulary is
  re-parented.

## FHIR operations: code in, answer out

[Open the group in the reference →](/terminology-api/fhir-operations) · taught in [Validating a code](/rail/reference/Terminology-Validating-Codes)

All of these are `GET`, all return a FHIR `Parameters` resource, and all are version-aware.

<Wire
  rows={[
    { call: "$lookup", does: "Resolve a code's display, definition, designations and properties.", keep: "display" },
    { call: "$validate-code (code system)", does: "Does this code exist, and is it active?", keep: "result" },
    { call: "$validate-code (value set)", does: "Is this code a member of this value set? The binding check for a form field.", keep: "result" },
    { call: "$subsumes", does: "Relationship between two codes: equivalent, subsumes, subsumed-by, or not-subsumed.", keep: "outcome" },
    { call: "$find-matches", does: "Rank concepts by free-text match within one system, for autocompletion against a known vocabulary.", keep: "matches" },
    { call: "$translate (concept map)", does: "Source code to target mapping, one match per target. This is the ICD-11 to ICD-10 crosswalk and anything like it. It is grouped under concept maps below, because using it well is mostly about reading the equivalence.", keep: "the target code" },
  ]}
/>

  `$validate-code` always answers `200`. Whether the code is valid is in the `result` parameter of the
  body, not in the status. An integration that branches on the status code will treat every invalid
  code as accepted.

## Value sets: membership, and why

[Open the group in the reference →](/terminology-api/value-sets) · taught in [Fetching a coded list](/rail/reference/Value-Sets)

<Wire
  rows={[
    { call: "GET /value-sets/{short code}/expansion/", does: "The member list. Same response shape whether it was precomputed or resolved on the spot.", keep: "codes" },
    { call: "GET /value-sets/{short code}/staleness/", does: "Whether the stored expansion still reflects its source systems. Poll this rather than re-expanding blindly.", keep: "stale or not" },
    { call: "GET /value-sets/{short code}/compose/", does: "The include and exclude rules the expansion was built from, which is the answer to 'why is this code in here?'", keep: "—" },
    { call: "GET /value-sets/{short code}/used-in/", does: "Where this value set is bound.", keep: "—" },
  ]}
/>

## Versioned reads: pinning, and auditing

[Open the group in the reference →](/terminology-api/versioned-reads) · taught in [Pinning to a release](/rail/reference/Terminology-Pinning-Versions)

Once you are live, this is the group you lean on hardest, because it is how you stop a vocabulary
change from becoming an incident.

<BuildSequence
  steps={[
    {
      do: "Pin with ?version=serving",
      detail:
        "A frozen read of whatever the artefact currently resolves to, without having to look up its number first. This is the default an integration should use.",
    },
    {
      do: "Pin harder with a version_id",
      detail:
        "Exactly what was frozen at that release, and only released versions are honoured. A version that held ten concepts keeps returning ten however many the working copy has since gained. That is the point, and it is why a pinned read is cacheable indefinitely.",
    },
    {
      do: "Diff with /changed/",
      detail:
        "The working copy against the serving version. A modified row carries both the before and after objects, so you can show what actually changed rather than only that something did.",
    },
    {
      do: "Read the ladder with /versions/",
      detail:
        "Every version newest-first, flagged is_serving, with pin_mode and pinned_version. This is what tells you whether serving is following the newest release or an owner's deliberate pin.",
    },
    {
      do: "Log the version alongside the value",
      detail:
        "Whatever you store a coded value on, store which version you read it at. When a code stops being accepted months later, that record is what lets you answer the question instead of guessing at it.",
    },
  ]}
/>

## Benefits and rates

[Open the group in the reference →](/terminology-api/benefits-and-rates) · taught in [What a cover pays for](/rail/guides/Benefit-Tree)

Two groups you will meet on the rail rather than in a general terminology client.

Benefits resolve in layers. Library → scheme → panel, each overlaying sparse overrides on the one
beneath. Resolve one node, or take the whole set in a single pass rather than making a request per
concept.

<Wire
  rows={[
    { call: "GET /code-systems/{scheme}/effective/{node}/", does: "One node resolved under a scheme, with a ?version= read overlaying the profile as it stood at that release.", keep: "the resolved node" },
    { call: "GET /code-systems/{scheme}/effective/", does: "The whole set in one pass. Prefer this to N single-node calls.", keep: "the resolved set" },
    { call: "GET /panels/{panel}/effective/", does: "The same resolution with the panel layer on top.", keep: "the resolved set" },
    { call: "GET /panels/{panel}/$lookup/", does: "Panels carry the same FHIR operation set as code systems.", keep: "—" },
  ]}
/>

Rates are release-gated. Only a released version's lines are payable, so an agreement carrying
nothing but an open draft resolves to no price at all. That is a correct answer rather than a
missing one.

<Wire
  rows={[
    { call: "GET /rates/effective/", does: "One scheme, one node, returning the full library → scheme → panel → provider envelope.", keep: "the effective rate" },
    { call: "POST /rates/effective/lookup/", does: "Many schemes and nodes in one round-trip. A scheme the facility is not empanelled for simply does not appear.", keep: "the envelope per node" },
  ]}
/>

## Concept maps: code in, other vocabulary out

[Open the group in the reference →](/terminology-api/concept-maps) · taught in [Translating between vocabularies](/rail/reference/Terminology-Concept-Maps)

<Wire
  rows={[
    { call: "GET /concept-maps/", does: "Find a map by source and target system, by canonical_url, or by short code. Public for published maps.", keep: "the map id" },
    { call: "GET /concept-maps/{short code}/$translate/?code=", does: "One code in, targets out, each with an equivalence. This is the crosswalk call.", keep: "the target code" },
    { call: "GET /concept-maps/{short code}/entries/", does: "Every row, filterable by equivalence and by whether it is mapped. This is where a positive no-mapping declaration is visible, since $translate hides those.", keep: "no_map, no_map_reason" },
    { call: "GET /concept-maps/{short code}/concept-map.json", does: "The whole map as FHIR, for loading a crosswalk locally rather than calling per code.", keep: "the resource" },
  ]}
/>

## Getting the data out

[Open the group in the reference →](/terminology-api/getting-the-data-out) · taught in [Getting the data you need](/rail/reference/Terminology-Getting-Data)

<Wire
  rows={[
    { call: "GET /code-systems/{short code}/export/", does: "One system as FHIR R4, synchronously. It is bounded, so above the inline limit it answers 413 and names the release job. ?_summary=true is the cheap header-only read.", keep: "the resource" },
    { call: "POST /release-jobs/", does: "The asynchronous export that hands you a file: FHIR, CSV, XLSX or bare codes, in FULL, SNAPSHOT or DELTA mode. DELTA is how a local copy updates incrementally.", keep: "the job id" },
    { call: "POST /release-jobs/preview/", does: "Same body, but a dry run. Counts and sample rows, with nothing stored.", keep: "row_count" },
    { call: "GET /release-jobs/{id}/ · /download/", does: "Poll (public, no token) then download (token, redirects to the live presigned URL).", keep: "status" },
  ]}
/>

## Search

[Open the group in the reference →](/terminology-api/search)

<Wire
  rows={[
    { call: "GET /search/", does: "Across concepts, systems, value sets and maps. Anonymous callers are allowed.", keep: "hits with their path" },
    { call: "GET /search/typeahead/", does: "Concept-only and latency-shaped for an autocomplete box. Requires a token, unlike the general search.", keep: "hits" },
  ]}
/>

  `POST /bulk/export/code-system/{short code}/` queues a CSV and answers `202` with a confirmation
  and no job id, so there is nothing to poll and no link to follow. Where you need the file back,
  use
  [a release job](/rail/reference/Terminology-Getting-Data#for-a-person--csv-excel-or-a-bare-code-list).

## What to build against

<BuildSequence
  steps={[
    { do: "Read serving rather than latest", detail: "Pin every runtime read to the serving version so an unreleased draft can never reach a patient-facing screen." },
    { do: "Validate rather than assume", detail: "Use $validate-code at the boundary where a code enters your system, and read the result parameter rather than the status." },
    { do: "Poll staleness, do not re-expand", detail: "Re-expanding a large value set on a schedule is expensive and usually unnecessary." },
    { do: "Log the version with the value", detail: "When a code stops being accepted, the first question is which version you were reading. Store it so you can answer that." },
  ]}
/>

**Next:** [Value sets and code systems](/rail/reference/Value-Sets) ·
[Error dictionary](/rail/reference/Errors)

---

## /rail/reference/Terminology-Validating-Codes

# Validating a code

  Check a code where it enters your system, rather than where it leaves. By the time a claim is
  rejected for an unrecognised code, the patient has gone home and the correction costs a person
  rather than a round-trip.

## Two questions that look like one

"Is this code valid?" is two questions, and they have different endpoints because they have
different answers.

<Wire
  rows={[
    { call: "Does this code exist in this system, and is it active?", does: "A question about the vocabulary. NATIONAL_ID is a real identifier type. NATIONAL-ID, with a hyphen, is not.", keep: "$validate-code on the code system" },
    { call: "Is this code allowed in this field?", does: "A question about the binding. A withdrawn identifier type still exists in the vocabulary. It is simply not offered any more, and existing in the vocabulary is not the same as being allowed in the field.", keep: "$validate-code on the value set" },
  ]}
/>

The second is almost always the one you want on a form. A field is bound to a value set, and the
question at the boundary is whether what arrived belongs in that set, not whether it exists
somewhere in the wider vocabulary.

  `$validate-code` answers `200` whether the code is valid or not. The verdict is the `result`
  parameter inside the FHIR `Parameters` body. An integration that branches on the status code
  treats every invalid code as accepted, and it will pass every test you write against valid
  input.

## What the answer looks like

Both operations return a FHIR `Parameters` resource. Three parameters matter:

<Wire
  rows={[
    { call: "result", does: "The verdict, as a boolean. This is the only field your branch should read.", keep: "result" },
    { call: "display", does: "The label, when the code resolved. Useful to render back at the operator so they can see what they matched.", keep: "nothing" },
    { call: "message", does: "Why it failed, when it did. Log it: 'invalid code' with no reason is a support ticket rather than a fix.", keep: "message" },
  ]}
/>

## Where each check belongs

<Wireframe
  title="Add a diagnosis"
  actor="Clinician"
  rows={[
    [{ label: "Diagnosis code", from: "1A00", kind: "field", span: 2 },
     { label: "Cholera", note: "Resolved, with the display returned by the service", tone: "positive", span: 2 }],
    [{ label: "Diagnosis code", from: "1AOO", kind: "field", span: 2 },
     { label: "Not a code in ICD-11", note: "Letter O typed for a zero. Caught here, not at submission.", tone: "negative", span: 2 }],
    [{ label: "Save diagnosis", kind: "action", span: 4 }],
  ]}
  caption="Both calls returned 200. The difference is entirely inside the body, which is why the status code is the wrong thing to branch on."
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    participant U as Clinician
    participant H as Your HMIS
    participant T as Terminology service

    U->>H: Types a code, leaves the field
    H->>T: GET /value-sets/{short code}/$validate-code/?code=1A00&version=serving
    T-->>H: 200 · Parameters { result: true, display: "Cholera" }
    Note over H: Read result, not the status.
    H-->>U: Shows "Cholera" beside the field

    U->>H: Types 1AOO
    H->>T: Same call
    T-->>H: 200 · Parameters { result: false, message: "..." }
    Note over H: Still a 200.
    H-->>U: Marks the field, keeps the message in the log
`} />

<Mermaid chart={`flowchart TD
    A["A code enters your system"] --> B{"From where?"}
    B -- "An operator typed it" --> C["Validate against the bound value set<br/>as the field loses focus"]
    B -- "Picked from a fetched list" --> D["Already valid at fetch time,<br/>but the list may be stale"]
    B -- "An interface or import" --> E["Validate every row.<br/>This is the path nobody checks."]
    C --> F{"result true?"}
    D --> G["Check your cache version<br/>against the serving version"]
    E --> F
    F -- No --> H["Reject at the boundary,<br/>log the message"]
    F -- Yes --> I["Store the code and the version"]
    G -- Stale --> J["Re-sync, then revalidate<br/>anything not yet submitted"]
    G -- Current --> I
`} />

## The calls

<ApiRef method="GET" path="/value-sets/{short code}/$validate-code/?code={code}&version=serving" to="/terminology-api/fhir-operations" keep="result">
  Is this code a member of this value set? The binding check for a form field, and the one you
  want most of the time.
</ApiRef>

<ApiRef method="GET" path="/code-systems/{system}/$validate-code/?code={code}&version=serving" to="/terminology-api/fhir-operations" keep="result">
  Does this code exist in this system, and is it active? A question about the vocabulary rather
  than the field.
</ApiRef>

<ApiRef method="GET" path="/code-systems/{system}/$lookup/?code={code}" to="/terminology-api/fhir-operations" keep="display">
  What does this code mean? Display, definition, designations and properties. This is how you
  render a stored code you never stored a label for.
</ApiRef>

  Storing the display text alongside the code feels like a saving and is a liability: when the
  wording is corrected upstream, your records now disagree with the vocabulary and you cannot tell
  which of the two is right. Store the code and the version you read it at, and resolve the label
  with `$lookup` when you need to render it.

## Translating rather than coding twice

Some payers are still on ICD-10 while diagnoses are coded in ICD-11. The answer is not to store
both.

<ApiRef method="GET" path="/concept-maps/{short code}/$translate/?code={code}" to="/terminology-api/concept-maps" keep="the target code">
  The equivalent code in another vocabulary, one match per target.
</ApiRef>

Code once in the primary vocabulary, and let the map resolve the rest. A system that stores the
older representation as its primary one has committed to a migration it has not scheduled.

There is more to this than the one call. Which map to use, what an equivalence promises, and why
a `result: false` means two different things are covered in
[translating between vocabularies](/rail/reference/Terminology-Concept-Maps).

## Building the check in

<BuildSequence
  steps={[
    {
      do: "Validate at the boundary, not at submission",
      detail:
        "Every place a code can enter: a typed field, an import, an interface from a third-party system. The import is the one that is usually missed, and it is the one that arrives at volume.",
    },
    {
      do: "Read the result parameter, never the status code",
      detail:
        "Write this once, in one helper, so no call site can get it wrong. A helper that returns a boolean from the body is the whole fix.",
    },
    {
      do: "Pin the check to the same version as the picker",
      detail:
        "Validating against serving while your dropdown was populated from a cached older release will reject codes you offered. One version string, read in both places.",
    },
    {
      do: "Log the message on failure",
      detail:
        "The reason is in the body. Discarding it turns every invalid code into the same unhelpful line in your log.",
    },
    {
      do: "Do not validate in a loop over a large import",
      detail:
        "Fetch the value set expansion once and check membership locally, then validate individually only what failed. One call per row of a ten thousand row import is a self-inflicted outage.",
    },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Submission, in production only",
      symptom: "\"Invalid codes are getting through and we validate everything\"",
      cause:
        "The check branches on the HTTP status, which is 200 for an invalid code. Read the result parameter.",
    },
    {
      where: "A form the user filled correctly",
      symptom: "\"It rejects a code we offered in our own dropdown\"",
      cause:
        "The picker and the validator are reading different versions. Pin both to the same one.",
    },
    {
      where: "A bulk import",
      symptom: "\"The import takes hours, or times out\"",
      cause:
        "One validation call per row. Expand the value set once and check membership in memory.",
    },
    {
      where: "Rendering an old record",
      symptom: "\"The label we show does not match the payer's statement\"",
      cause:
        "A display string stored at capture time and never revisited. Store the code, resolve the label.",
    },
    {
      where: "A third-party interface",
      symptom: "\"Codes from the lab system are rejected downstream\"",
      cause:
        "Validation was built on the typed-entry path only. Every entry point needs the same boundary check.",
    },
  ]}
/>

**Next:** [Translating between vocabularies](/rail/reference/Terminology-Concept-Maps) ·
[Pinning to a release](/rail/reference/Terminology-Pinning-Versions) ·
[Error dictionary](/rail/reference/Errors)

---

## /rail/reference/Terminology-Walking-The-Tree

# Walking a concept tree

  A vocabulary with thirty thousand entries will not fit in a dropdown. It is a tree, and the list
  an endpoint hands you often starts partway down it, so the first thing to learn is how to climb.

## What goes wrong if you treat it as a list

Small coded lists are flat. Identifier types are eleven entries with no structure: every concept
comes back at `depth: 0`, and a dropdown is the correct interface.

Interventions are not that. There are tens of thousands of them, arranged in layers: benefits,
then categories, then interventions, then services, with protocols and drugs beneath those.
Three things follow, and each one bites a different integration:

<Wire
  rows={[
    { call: "You cannot render it all", does: "A single fetch of every concept is slow, and far too large to use as a picker. Users need to narrow down, which means the interface has to open one level at a time.", keep: "roots first, children on demand" },
    { call: "The list may start partway down", does: "Some endpoints return interventions at the sub-intervention level rather than at the top. What you receive is a set of leaves rather than a set of roots, so a naive renderer shows you the bottom of the tree with no idea what it belongs to.", keep: "climb with /parents/" },
    { call: "Grouping nodes are not selectable", does: "A category is a heading. If you render every concept as an option, a user can pick a heading, and the claim that results is rejected for a code that was never billable.", keep: "concept_class" },
  ]}
/>

The second one costs the most, because nothing in the response tells you it happened. You get a
well-formed list of concepts, each with a real code, and it looks complete.

  A concept carries `depth`, `parent_code` and `child_count`. If everything you received has a
  non-null `parent_code`, you are holding leaves. If everything has `child_count: 0` and a
  non-zero `depth`, you are certainly at the bottom. Check this once when you first integrate a
  vocabulary, rather than guessing at it response by response.

## The two directions

Everything here is one of two moves: down, to offer choices, or up, to work out what a leaf
belongs to.

<Wireframe
  title="Select an intervention"
  actor="Clinician"
  rows={[
    [{ label: "Search interventions", from: "GET /search/typeahead/?q=echo", kind: "field", span: 4 }],
    [{ label: "▸  Surgical services", note: "Grouping node, so a heading rather than an option", kind: "text", span: 4 }],
    [{ label: "▾  Cardiology", note: "Opened. One call fetched this level.", kind: "text", span: 4 }],
    [{ label: "      ▾  Echocardiography", note: "Opened", kind: "text", span: 4 }],
    [{ label: "            Transthoracic echo", from: "INT-CARD-ECHO-TTE", tone: "positive", span: 2 },
     { label: "            Transoesophageal echo", from: "INT-CARD-ECHO-TOE", tone: "positive", span: 2 }],
    [{ label: "▸  Diagnostic imaging", note: "Never fetched, because nobody has opened it", kind: "text", span: 4 }],
  ]}
  caption="Three fetches made this screen: the roots, then the children of Cardiology, then the children of Echocardiography. The unopened branches have never been requested, and the two green rows are the only ones a user may select."
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    participant U as Operator
    participant H as Your HMIS
    participant T as Terminology service

    H->>T: GET /concepts/roots/?system=INTERVENTIONS&version=serving
    T-->>H: The top layer, with child_count on each
    Note over H: Render only nodes with child_count > 0<br/>as openable.

    U->>H: Opens "Cardiology"
    H->>T: GET /concepts/{id}/children/
    T-->>H: One level down
    Note over H: Cache it. Reopening a branch<br/>should not re-fetch.

    U->>H: Picks a leaf
    Note over H: Store the code. Never the display text.
`} />

<Mermaid chart={`flowchart TD
    A["A list of concepts arrives"] --> B{"Every parent_code non-null?"}
    B -- "Yes, these are leaves" --> C["GET /{id}/ancestors/<br/>to place them in the tree"]
    B -- "No, these include roots" --> D["Render as the top layer"]
    C --> E["Group the leaves under<br/>their resolved ancestors"]
    E --> F["Render the tree"]
    D --> F
    F --> G{"User opens a node?"}
    G -- Yes --> H["GET /{id}/children/, cache it"]
    H --> G
    G -- "Picks a node" --> I{"concept_class is a grouping?"}
    I -- Yes --> J["Not selectable,<br/>it is a heading"]
    I -- No --> K["Store the code"]
`} />

## The calls

One thing to settle before the calls. Code systems, value sets and concept maps are all addressable
by their short code, so `/code-systems/IDENTIFIER-TYPES/` works exactly as `/code-systems/1251/` does.
Concepts are the exception: a concept code is unique only inside its own system, so the concept
routes below take a numeric id. Resolve it once from the list read and keep it beside the code you
store:

<TryIt
  title="Resolve a concept id from the code you hold"
  path="/concepts/?system=IDENTIFIER-TYPES&search=NATIONAL_ID&version=serving"
  keep="id, alongside the code"
>
  The list read is addressed by short code; the `id` on the row it returns is what the tree calls
  below need. Storing the id next to the code saves this lookup on every subsequent walk, and unlike
  a display string, an id is safe to cache because it never changes.
</TryIt>

Down the tree, one level at a time:

<ApiRef method="GET" path="/concepts/roots/?system={system}&version=serving" to="/terminology-api/concepts" keep="the root codes">
  The top layer of a vocabulary. Start here for anything you cannot render whole.
</ApiRef>

<ApiRef method="GET" path="/concepts/{id}/children/" to="/terminology-api/concepts">
  The direct children of one node. Called when a user opens a branch, and cached so reopening it
  does not re-fetch.
</ApiRef>

Up the tree, from a leaf you were handed:

<ApiRef method="GET" path="/concepts/{id}/parents/" to="/terminology-api/concepts">
  One level up. Note the plural: a concept may have more than one parent, and a breadcrumb that
  renders a single path silently picks one of them.
</ApiRef>

<ApiRef method="GET" path="/concepts/{id}/ancestors/" to="/terminology-api/concepts">
  Every ancestor, transitively. This is what turns a list of leaves into a tree you can render.
</ApiRef>

And the whole subtree, when you genuinely need it:

<ApiRef method="GET" path="/concepts/{id}/descendants/" to="/terminology-api/concepts">
  Everything beneath a node, transitively. Useful for a rule that applies to a whole branch, and
  for checking whether a billed code falls under an approved one.
</ApiRef>

  Ancestors and descendants are served from a closure table. Fetching `/children/` repeatedly and
  assembling the transitive set client-side is slower, and it drifts the moment the vocabulary is
  re-parented upstream, which happens without your release cycle noticing.

## Is this code under that one?

A common question at Bill: the preauthorisation approved a category, and a specific service was
performed. Does the service fall under what was approved?

Do not answer this by walking descendants and searching the list. There is one call:

<ApiRef method="GET" path="/code-systems/{system}/$subsumes/?codeA={approved}&codeB={billed}" to="/terminology-api/fhir-operations" keep="outcome">
  How two codes relate: `equivalent`, `subsumes`, `subsumed-by` or `not-subsumed`.
</ApiRef>

`subsumes` means `codeA` is the broader one, so an approved category subsuming a billed service is
the answer you want. `not-subsumed` means the two are in unrelated branches, which is the case
worth surfacing to an operator before submission rather than after rejection.

## Building it so it stays fast

<BuildSequence
  steps={[
    {
      do: "Fetch roots once, at start-up",
      detail:
        "The top layer of a vocabulary changes rarely. Load it with the rest of your terminology sync rather than when a patient is waiting.",
    },
    {
      do: "Cache each branch by node id",
      detail:
        "A user who collapses and reopens Cardiology should not cost you a round-trip. Cache the children keyed on the node, and invalidate the whole cache on a version change rather than per node.",
    },
    {
      do: "Search server-side, do not filter your cache",
      detail:
        "A search box that filters only the branches already fetched will confidently report no results for a code that exists. Send the term to the service.",
    },
    {
      do: "Use concept_class to decide what is selectable",
      detail:
        "Grouping nodes render as headings. Do not infer this from child_count, because a leaf category with nothing under it yet is still not billable.",
    },
    {
      do: "Store the code and the version, never the display",
      detail:
        "A display string you stored is a claim you cannot defend once the wording changes. The code is what was actually chosen, and the label is only one way of showing it.",
    },
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "First render of a large vocabulary",
      symptom: "\"The picker takes twelve seconds to open\"",
      cause:
        "Every concept fetched up front. Fetch roots, then children on demand, since the user only ever sees one branch at a time anyway.",
    },
    {
      where: "A list that arrives partway down",
      symptom: "\"We are showing sub-services with no idea what they belong to\"",
      cause:
        "Leaves rendered as though they were roots. Resolve ancestors and group under them.",
    },
    {
      where: "Submission",
      symptom: "\"The code was rejected and it is definitely in the list\"",
      cause:
        "A grouping node was offered as an option. Read concept_class before rendering something selectable.",
    },
    {
      where: "Search",
      symptom: "\"Searching finds nothing, but browsing finds it\"",
      cause:
        "The search box is filtering the local cache rather than calling the service, so it can only find branches already opened.",
    },
    {
      where: "Weeks after a terminology release",
      symptom: "\"Our tree shows a parent that no longer exists\"",
      cause:
        "A client-assembled hierarchy, cached and never invalidated. Read ancestors from the service and key the cache on the version.",
    },
  ]}
/>

**Next:** [Validating a code](/rail/reference/Terminology-Validating-Codes) ·
[Pinning to a release](/rail/reference/Terminology-Pinning-Versions) · or the whole surface at
[the terminology service](/rail/reference/Terminology-Service)

---

## /rail/reference/Time-Limits

# Not yet settled

  Some of the rail's rules are still being confirmed. It does more damage to publish them as settled
  than to publish them as open, so this page collects them and says plainly what is not known yet.

## Why this page exists rather than a table of numbers

Time limits decide the shape of a provider's software. If the claim time bar is 120 days, you can
reconcile once a month. If it is 14 days, you need a daily worklist, an alerting rule and somebody
whose job it is to watch it. Those are two different products.

The training material and the conformance specification currently give different answers, and
system configuration defaults give a third in places. Building to the wrong one loses money quietly,
so the figures below are set out as a conflict and not as guidance.

  Nothing here is safe to hard-code. Where you need a limit today, ask for the production value in
  writing, and keep it in configuration instead of a condition, so that changing it later does not
  need a release.

## The disagreements

<CostTable
  rows={[
    {
      where: "Claim time bar",
      symptom: "~120 days versus 14 days",
      cause:
        "14 days is stated from claim creation for outpatient, and from discharge for inpatient. If 14 is right, a monthly submission rhythm loses claims, which makes this the most consequential of the conflicts.",
    },
    {
      where: "Outpatient authorisation validity",
      symptom: "~30 days versus 180 days",
      cause:
        "Decides how long an authorisation can sit before the visit has to be opened against it.",
    },
    {
      where: "Inpatient authorisation validity",
      symptom: "~1 year versus 180 days",
      cause:
        "The same question over a longer horizon, and the two sources are half a year apart.",
    },
    {
      where: "Elective preauthorisation",
      symptom: "45 days to start the visit versus 7 days from approval",
      cause:
        "The number differs and so does the starting point, which is either issue or approval. You need both stated before you can build a countdown.",
    },
    {
      where: "Emergency claim",
      symptom: "Not stated versus 24 hours from creation",
      cause:
        "If the window is 24 hours, emergency submission has to be alarmed on the same day instead of queued for later.",
    },
    {
      where: "Missing-documents resubmission",
      symptom: "Not stated versus 14 days",
      cause:
        "After that it is rejected and cannot be resubmitted at all. An operator should be able to see a terminal deadline in the interface, rather than learn about it from the rejection.",
    },
    {
      where: "One-time code validity",
      symptom: "Not stated versus 5 minutes",
      cause:
        "Five minutes changes the consent screen, which then needs a visible countdown and a resend instead of a passive input box.",
    },
  ]}
/>

## What is not in dispute

Two windows are consistent across sources. Their shape is safe to design around even if the exact
figures move.

<Wire
  rows={[
    { call: "Visit open, outpatient", does: "Roughly a month before it has to be closed.", keep: "Close visits deliberately; do not rely on the ceiling" },
    { call: "Visit open, inpatient", does: "Roughly a year, long enough that the ceiling will not be your constraint.", keep: "Discharge closes it, not the clock" },
  ]}
/>

## Build so that a change is not a release

A better guess is not what an unresolved limit needs. Hold every clock in one place, where it can be
corrected without a code change.

<BuildSequence
  steps={[
    {
      do: "Put every limit in configuration",
      detail:
        "One named module, with the source of each value recorded beside it. Inline a limit in a condition and nobody will be able to find it when it changes.",
    },
    {
      do: "Show the deadline, do not enforce it silently",
      detail:
        "Put the date a claim must be submitted by on the claim itself. An operator who can see the deadline will meet it. If it is hidden, the first sign of it is a rejection.",
    },
    {
      do: "Alert on the approach, not the breach",
      detail:
        "A worklist that flags at 70% of the window elapsed is useful. One that reports what has already expired only tells you what you lost.",
    },
    {
      do: "Log the value you used",
      detail:
        "When a limit turns out to have been wrong, the first question is which number your system applied and since when. Make that answerable.",
    },
  ]}
/>

## Enforcement that may not be on yet

Two checks are published as rules but may not be enforced in production yet. The risk is the same in
both cases, and it is one-sided: an integration that ignores the rule passes today and starts
failing on the day the check is switched on.

<Wire
  rows={[
    { call: "Attachment checking", does: "Required-document rules may not be enforced at submission today. Build to the published per-procedure requirements whatever the environment happens to accept.", keep: "the published list" },
    { call: "Interface-only rules", does: "Some prescription and primary-care diagnosis rules may be enforced in the interface today and not in the API, so a direct integration is not stopped by them.", keep: "the rule, not the behaviour" },
  ]}
/>

## Workflows still being completed

<Wire
  rows={[
    { call: "The whitelist reason list", does: "The reasons offered differ between systems, so a reason you send may be ignored. Record what the operator chose, and do not build a picker on values that are not agreed.", keep: "your own record" },
    { call: "Removing a whitelist", does: "The current mechanism is being corrected, so do not build a removal path against it yet.", keep: "—" },
    { call: "Incoming referrals", does: "The receiving-side workflow is still being completed. An inbound queue is the right thing to build, as long as you do not treat it as final.", keep: "—" },
    { call: "Billing above the tariff", does: "It is not settled whether public-officer members bypass the tariff cap for all procedures or only some, so do not encode a blanket rule.", keep: "—" },
    { call: "Excess of loss", does: "It is still being decided whether an integrator bills against it directly or the rail applies it.", keep: "—" },
    { call: "Multiple doctors", does: "The production setting that controls whether several doctors may be attached is an open question, as is the behaviour when it is off.", keep: "—" },
    { call: "Which proofs can be reused", does: "Discharge is settled as standalone. Whether an eligibility or cover-view proof may be spent on opening a visit is not, so re-authenticate where you are unsure.", keep: "—" },
    { call: "Freshness windows", does: "It is being decided whether the window is set per factor, per purpose, or as one default with overrides. Read the expiry from the record instead of assuming a duration.", keep: "expires_at" },
  ]}
/>

  Put it in configuration, not in a condition. Log the value you applied and when. Where a rule is
  unconfirmed, build to the stricter reading: an integration that collects a document it did not
  need loses nothing, while one that skipped a required document loses a claim.

## Getting this resolved

These will be settled and published as single values. Until they are, treat any figure you are
given verbally as unconfirmed, record who gave it to you and when, and keep it in configuration so
that the correction does not need a code change. If a limit matters to your design, ask for it in
writing before you build the behaviour that depends on it.

**Next:** [Error dictionary](/rail/reference/Errors) · [Value sets and code systems](/rail/reference/Value-Sets)

---

## /rail/reference/Value-Sets

# Value sets and code systems

  Every coded list in this documentation can be fetched from the terminology service. Copy one
  into a constant and it will be wrong the next time the list changes.

## Why you fetch rather than embed

Coded lists move. Identifier types get added and withdrawn, document types grow as new
interventions are onboarded, and diagnosis vocabularies are reversioned. A list you copy today
will be quietly out of date in a few months, and when that happens the failure tends to look
like something wrong with the patient's record rather than something wrong with your data.

Every list below is served by the terminology service, versioned, and safe to cache. Fetch on a
schedule, keep a local copy, and key that copy on the `version` you were handed.

This page covers which coded lists the rail uses and how to fetch one. The same list also comes
in other shapes (paged JSON, FHIR, CSV, Excel, a bare code list, and the import path back in), and
those are in [getting the data you need](/rail/reference/Terminology-Getting-Data). The rest of the
service, meaning validating a code, walking a hierarchy, pinning to a released version, translating
between vocabularies, or resolving a rate, is in
[the terminology service](/rail/reference/Terminology-Service).

## Which list do you need?

Every row below is a code system on the terminology service, and all of them are read with the
single call in [Retrieving a list](#retrieving-a-list-from-the-terminology-service). Swap the
`system` parameter and nothing else changes. Each row links to the page where the list is
explained in context.

| Code system | What it is for | Taught at |
|-------------|----------------|-----------|
| `IDENTIFIER-TYPES` | The document types a front desk may choose from when resolving a patient | [01 · Identify](/rail/stops/Identify) |
| `HEALTHCARE-WORKER-REGULATORS` † | The bodies that register practitioners, which is half of a clinician's identifier | [01 · Identify](/rail/stops/Identify) |
| `PRACTITIONER-CADRES` † | Discipline and speciality, where a benefit requires a named one | [01 · Identify](/rail/stops/Identify) |
| `ICD-11` | Diagnosis coding at preauthorisation, with an ICD-10 crosswalk for payers still on it | [5 · Preauth](/rail/stops/Preauth) |
| Error codes | Every error the rail can return, published as terminology so you can generate an enum | [Error dictionary](/rail/reference/Errors) |

† These two short codes are unconfirmed. They are the names we expect rather than names checked
against the live catalogue. `IDENTIFIER-TYPES` is confirmed and these two are not, so resolve them
before you wire them in, with `GET /code-systems/?search=regulator` and `?search=cadre`. A 404 on
the detail route is a real answer, because the route accepts either a short code or an id.

Two habits apply whichever list you are using.

Pre-load rather than fetching during a visit. A pick-list fetched while a patient waits can also
fail while that patient waits, so sync on a schedule instead.

Filter when you are building a picker, but not when you are reading history. Only
`is_active: true` belongs in a dropdown, and withdrawn codes still have to render when you are
interpreting a record from last year.

## One call, whichever list you need

There is no per-vocabulary endpoint. Identifier types have no `/identifier-type` route of their
own. They are one code system among many on the terminology service, read through the same call as
every other list on this page. The only thing that changes between them is the `system` you pass.

<TryIt
  title="Read any coded list"
  path="/concepts/?system=IDENTIFIER-TYPES&version=serving&page_size=50"
  keep="code, display, version"
>
  Swap `IDENTIFIER-TYPES` for any short code in the table above and the rest of the call is
  identical: same envelope, same paging, same `version=serving`. That is why a terminology layer in
  your own code should take the system as an argument instead of carrying one function per list.
</TryIt>

<ApiRef method="GET" path="/concepts/?system={short code}&version=serving" to="/terminology-api/concepts" keep="code, display">
  Every parameter this call accepts, in the terminology reference: filters for hierarchy, status
  and concept class, and the full `?version=` contract.
</ApiRef>

Two things to notice in the envelope it returns.

`status` matters. A withdrawn code may still appear, marked inactive, so that historical records
referencing it stay readable. Filter on `status: "active"` when you populate a picker, and do not
filter when you are interpreting stored data.

`version` is your cache key. Compare it instead of re-fetching blindly, and log it. When a coded
value stops being accepted, the first question anyone asks is which version you were on.

## Retrieving a list from the terminology service

Every coded list the rail uses is held in the terminology service as a code system, and every one
of them is fetched the same way: by API for a running integration, or as a spreadsheet for someone
who just needs to read it. None of it is specific to one vocabulary. Swap the `system` and the call
is identical.

```bash
BASE=https://ilm-dev.dha.go.ke/dev/ts/api/v2
```

### What needs a token, and what does not

The service splits in two, and knowing which half you are working in saves you an authentication
problem that did not need to happen.

<Wire
  rows={[
    { call: "GET /code-systems/", does: "Which code systems exist, with their short codes and ids. Public, so it answers with no credential at all.", keep: "short_code, id" },
    { call: "GET /code-systems/{id}/", does: "One code system's detail. Also public.", keep: "canonical url" },
    { call: "GET /value-sets/", does: "Which value sets exist. Also public.", keep: "id" },
    { call: "GET /concepts/…", does: "The codes themselves. Requires a token issued by the terminology service's own realm.", keep: "code, display" },
    { call: "GET /code-systems/{id}/versions/, /summary/, /changed/, $lookup, expansions", does: "Everything else: versioned reads, FHIR operations, expansions. All of it needs that token.", keep: "—" },
  ]}
/>

Two consequences follow. You can discover the catalogue before you hold any credentials, which is
the quickest way to confirm a short code instead of guessing at it. And the public catalogue is
filtered: without a token you see only what is published openly, so a system you were expecting may
be invisible rather than missing.

### By API: the call to build against

```bash
curl -sS "$BASE/concepts/?system=IDENTIFIER-TYPES&version=serving&page_size=50" \
  -H "authorization: Bearer $TOKEN"
```

`version=serving` is the part that matters. It resolves to the latest approved release of that
code system. Omit it and you get whatever is in the source, drafts included, which is what you want
while you are authoring terminology and wrong in every integration.

```json
{
  "count": 11,
  "next": null,
  "page_size": 50,
  "current_page": 1,
  "total_pages": 1,
  "results": [
    {
      "code": "NATIONAL_ID",
      "display": "National ID",
      "code_system_short_code": "IDENTIFIER-TYPES",
      "code_system_canonical_url": "https://terminology.sil.advantage/CodeSystem/identifier-types",
      "uri": "https://terminology.sil.advantage/CodeSystem/identifier-types|NATIONAL_ID",
      "is_active": true,
      "status": "PUBLISHED",
      "parent_code": null,
      "depth": 0,
      "child_count": 0
    }
  ]
}
```

What to read from each concept, and what to ignore:

<Wire
  rows={[
    { call: "code", does: "The value you send on the wire, and the only thing you store", keep: "code" },
    { call: "display", does: "The label you render, never stored and never sent", keep: "—" },
    { call: "is_active + status", does: "Only a PUBLISHED and active concept belongs in a picker; a DRAFT never does", keep: "is_active" },
    { call: "parent_code, depth, child_count", does: "Hierarchy, where the vocabulary has one. Render it as a tree rather than a flat list", keep: "parent_code" },
    { call: "next, total_pages", does: "Paging. A sync that reads only the first page ships part of the vocabulary and still looks like it worked", keep: "next" },
  ]}
/>

Some systems have a hierarchy and some do not. Identifier types are flat: every concept is
`depth: 0`. A diagnosis system is nested, so `SYS-CARD` (a `Category`) parents `DIAG-CHF`, which in
turn parents left- and right-sided failure. Use `concept_class` to tell a grouping node from a
selectable one, and render a category as a heading in your dropdown rather than as an option.

  This is the intended use. Fetch with `version=serving` on a schedule, cache locally, filter
  to `is_active: true`, render `display`, submit `code`. It works the same way for identifier
  types, diagnoses, document types and everything after them.

### As a spreadsheet: the three-call release job

Excel and CSV do not come from `/concepts/`. They come from an asynchronous release job. You ask
for an export, poll until it finishes, then download it.

You need two ids: the code system's `artifact_id`, and a `version_id`.

```bash
# 1 · find the version to export
curl -sS "$BASE/code-systems/1251/" \
  -H "authorization: Bearer $TOKEN" -H 'x-variant: hie'
# -> draft_version: 1199, current_version: null
```

```bash
# 2 · create the job  (format: "CSV" for CSV instead)
curl -sS -X POST "$BASE/release-jobs/" \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -H 'x-active-tenant: <your tenant id>' \
  -H 'x-variant: hie' \
  -d '{
        "artifact_kind": "codesystem",
        "artifact_id": 1251,
        "version_id": 1199,
        "mode": "SNAPSHOT",
        "format": "XLSX",
        "include_inactive": false
      }'
# -> 201 { "id": 11, "status": "queued" }
```

```bash
# 3 · poll, then download
curl -sS "$BASE/release-jobs/11/"
# -> "status": "completed", "row_count": 11

curl -sSL -o identifier-types.xlsx "$BASE/release-jobs/11/download/" \
  -H "authorization: Bearer $TOKEN" -H 'x-variant: hie'
```

The export carries `code | display | definition | concept_class | parent | status |
effectiveTime`, one row per concept.

Four things are worth knowing before you build this.

`version_id` is required. Omit it and the create returns
`400 {"version_id":["This field is required."]}`. Take it from step 1: `draft_version` while a
system is still being authored, or a released version id once one exists.

Do not cache `output_file_url`. It is a shortened presigned link that is regenerated on every
poll, so each poll hands you a different URL. Hit `/release-jobs/{id}/download/` instead, which
redirects to the current one.

Polling needs no auth, but creating and downloading do. Job create needs
`terminology-service.releasejobviewset.create` and download needs `.read`. Reading job status is
open.

This path is for people, not for runtime. Use it to hand someone a list to review, or to seed a
mapping exercise. An integration reads `/concepts/?version=serving` rather than downloading
spreadsheets.

## Diagnosis coding, and the crosswalk

Diagnoses are coded in ICD-11. Exactly one primary diagnosis is required on a
preauthorisation, and duplicates are rejected.

Some payers are still on ICD-10. You do not code twice. A concept map on the terminology service
resolves it, through the same `$translate` operation any crosswalk uses:

<ApiRef method="GET" path="/concept-maps/{short code}/$translate/?code={code}" to="/terminology-api/concept-maps" keep="the target code, and its equivalence">
  The ICD-10 equivalent of an ICD-11 code, for payers that have not migrated.
</ApiRef>

Code once in ICD-11 and let the map resolve the rest. A system that stores ICD-10 as its primary
representation will have to migrate later.

Reading the answer takes a little more than lifting the target code out of it. The equivalence
matters, and a negative result can mean two different things, which is covered in
[translating between vocabularies](/rail/reference/Terminology-Concept-Maps).

## Standard codes and mapping

Before an item may be billed, it must be declared: you say what one of your price-list items
maps to, and the rail validates that the standard code is real and recognised, then computes
the paths onward to each payer's revenue codes.

This runs in one direction only. The rail does not infer what your item is; you declare it.
Anything never declared, or declared and rejected, stays off the claim entirely as
`UNMAPPED_CODE`.

  Medicines are validated against the pharmacy regulator's registry rather than the general
  standard-code space. A product that is not registered is not reimbursable, though it may
  still be sold as cash. That is an answer about payability, not about whether you may dispense
  it.

## Error codes as a value set

The error dictionary is itself published as terminology, so you can generate your error enum
rather than typing it:

<div className="rail-op-actions">
  <a className="rail-btn rail-btn--primary" href="/terminology/rail-errors.json" download>
    Flat JSON
  </a>
  <a className="rail-btn" href="/terminology/rail-errors.codesystem.json" download>
    CodeSystem
  </a>
  <a className="rail-btn" href="/terminology/rail-errors.valueset.json" download>
    ValueSet
  </a>
</div>

See the [error dictionary](/rail/reference/Errors) for the readable version.

## How to keep a local copy honest

<BuildSequence
  steps={[
    "Sync on a schedule rather than on demand. A pick-list fetched during a patient interaction can also fail during that interaction.",
    "Key your cache on the returned version string, and log it with every coded value you store.",
    "Page properly. A sync written against the default first page ships part of the vocabulary and still looks like it worked.",
    "Filter on status for pickers, and do not filter when you are interpreting stored history. Withdrawn codes still need to render.",
    "Store the code and never the display text. A display string you stored is impossible to defend once the wording changes.",
    "Generate enums at build time from the published value sets, so a new code turns up when you compile instead of in production.",
  ]}
/>

**Next:** [Getting the data you need](/rail/reference/Terminology-Getting-Data) ·
[Error dictionary](/rail/reference/Errors) · or see coded lists in use at
[02 · Verify cover](/rail/stops/Entitle)

---

## /rail/stops/Authenticate

# 00 · Authenticate

  Authenticate is the step where the rail learns which system is asking and where it is asking
  from. Every other stop is about a patient; this one is about your system.

## What this step is

Your system presents the credentials it was issued and gets back a token that says "this is a
known integrator". Nothing about a patient can happen until that token exists.

You establish two separate things here, and confusing them is the commonest way this stop
goes wrong.

<Wire
  rows={[
    { call: "Who you are", does: "A client id and secret exchanged for an access token. This is your identity as the vendor, and it does not change from one facility, patient, visit or day to the next.", keep: "access_token" },
    { call: "Which facility you are acting for", does: "Sent as headers on every call. You are one system serving many facilities, and almost every rule downstream (price, empanelment, which consent factors are offered) is scoped to this rather than to you.", keep: "facility code + its type" },
  ]}
/>

This matters more for an HMIS than it would for a single clinic's own software. Your token is
issued once to you, the vendor, and it does not change when the user switches site. The facility
does change, and it decides the answer. A correct token with the wrong or missing facility
authenticates perfectly and then fails three stops later, where the failure looks like something
else entirely: an empty benefit list for a member who is plainly covered, biometrics demanded at a
site that does not use them, a price that is wrong the same way every time.

Nothing in those symptoms mentions a facility, which is why this is a trap rather than an
ordinary mistake.

The rule that makes it work is that the token says who you are, the headers say where you are,
and the rail needs both on every call.

There are three things to do.

<BuildSequence
  steps={[
    {
      do: "Exchange credentials for a token",
      detail:
        "One call with your client id and secret. You get back an access token and the number of seconds it is good for.",
    },
    {
      do: "Derive the facility headers, do not configure them",
      detail:
        "Have one place in your HTTP client read the facility from whichever site the session belongs to, so no call site can omit it and no call can carry the wrong one. A hard-coded facility code works in a single-site pilot and then silently misprices everything the day a second site goes live.",
    },
    {
      do: "Decide where decisions get delivered",
      detail:
        "Preauthorisation and claim outcomes come back asynchronously, so the rail needs somewhere to send them. Register an endpoint here and every call uses it, or pass one per request in the X-Callback-Url header where a particular call needs its own. Settle this at 00 rather than finding out about it at Submit.",
    },
  ]}
/>

If you only remember one thing: <u>the facility headers are as required as the token, and both
belong in the HTTP client rather than at the call site.</u>

Two ways to look at the step: who answers whom, and what happens to the token over its life.

<Mermaid chart={`sequenceDiagram
    autonumber
    participant H as Your HMIS
    participant I as Identity service
    participant R as The rail

    H->>I: client_id + client_secret
    I-->>H: access_token, expires_in
    Note over H: Cache the token.<br/>Refresh before expiry, on a timer.
    H->>R: Any call + Bearer token + facility headers
    R-->>H: Answer, scoped to that facility
    Note over H,R: The secret is used once, here.<br/>Everything after it carries the token.
`} />

<Mermaid chart={`flowchart TD
    A["A call is about to be made"] --> B{Token cached and still fresh?}
    B -- Yes --> C["Send it, with the facility headers"]
    B -- "Expiring soon" --> D["Refresh on the timer,<br/>then send"]
    D --> C
    B -- "Already expired" --> E["401 on a patient-facing call,<br/>the case you can avoid"]
    E --> F["Refresh and retry once,<br/>then fix the timer"]
    C --> G{Facility headers present?}
    G -- No --> H["FACILITY_CONTEXT_MISSING<br/>or a strict-default refusal later"]
    G -- Yes --> I["Answer, scoped to the facility"]
`} />

## The call

Two calls make up this step. One exchanges credentials for a token. The other registers where
decisions should be delivered. Both are in the reference with every parameter, and with a **Try it** console for when the sandbox is live.

<Wire
  rows={[
    { call: "POST · token", does: "Exchanges your client id and secret for an access token, with the seconds it is valid for.", keep: "access_token, expires_in" },
    { call: "POST · callbacks", does: "Registers the endpoint that preauth, claim and remittance decisions are delivered to.", keep: "callback_id" },
  ]}
/>

Open [**00 · Authenticate in the Rail API reference**](/rail-api/00-authenticate) to read or run
both. They are the whole of this stop, and there is no wider authentication surface to go and
find: one grant type (`client_credentials`), tokens good for thirty minutes, and no refresh
token, so you request a new token on expiry rather than refreshing the old one.

  It is the one call in this documentation not made against the rail's gateway. The identity
  service issues the exchange on its own host, it is form-encoded rather than JSON, and it
  carries no bearer token of its own, because the credentials are the authentication. Everything
  after it goes to the rail with the token attached.

  The same operation is also published on its own, because the eTIMS branch needs it without the
  rail around it. There is one description rather than two copies: the rail's spec lifts that
  operation from the authentication spec when it is generated, and the build fails if the two ever
  stop matching.

Two things the reference will not tell you.

<Wire
  rows={[
    { call: "Cache it", does: "The reference shows one exchange. It does not tell you that fetching a token per request will get you throttled and make every call slow.", keep: "access_token + expiry" },
    { call: "Send the facility every time", does: "The reference lists the headers. Only this page tells you that leaving them out fails at Consent and the cover check rather than here.", keep: "facility headers" },
  ]}
/>

## Facility context travels in headers

They never travel in a request body, and you should not assemble them at each call site.

<Wire
  rows={[
    { call: "Authorization: Bearer …", does: "Identifies your system", keep: "access_token" },
    { call: "X-Facility-Id", does: "Identifies the facility the call is made from", keep: "facility code" },
    { call: "X-Facility-Id-Type", does: "Says which identifier scheme that code is in", keep: "id type" },
    { call: "X-Callback-Url", does: "Optional. Where this request's decision should go, if it should not go to your registered endpoint.", keep: "the URL you sent" },
  ]}
/>

Two of those three are required on every call. The callback header is the exception, and you send
it only when this request's outcome belongs somewhere other than the endpoint you registered.

If a facility identifier appears in a request body anywhere in your codebase, treat it as a bug
that will surface on a busy day. The header is the only channel the rail guarantees to honour.

  You exchange the client secret once, from a server you control, and store it in a secret
  manager. The token is what travels. Never log the token, never put it in a URL, and never
  ship the secret to a browser or a mobile client. Anyone holding a bearer credential can act
  as you.

## What you keep

<Wire
  rows={[
    { call: "access_token", does: "Sent on every subsequent call, at every stop", keep: "In memory, with its expiry" },
    { call: "expires_in", does: "What your refresh timer is set from. Log it, because a 401 is hard to explain if you cannot say when the token was due to run out.", keep: "Computed expiry" },
    { call: "Facility code and type", does: "Headers on every call. They scope pricing, empanelment and which consent factors are offered, so they belong to the session rather than to your deployment.", keep: "Resolved per session" },
    { call: "callback_id", does: "Proof a delivery endpoint is registered. Keep it even if you also send per-request callbacks, since the registered endpoint is the fallback for everything that does not carry a header.", keep: "Your integration record" },
  ]}
/>

## What breaks here

Almost nothing breaks *at* this stop, which is what makes it expensive. The failures surface
two or three stops away, and they do not look like authentication problems when they do.

<CostTable
  rows={[
    {
      where: "Every call, suddenly",
      symptom: "\"Everything returns 401 since this morning\"",
      cause:
        "The token expired and refresh is reactive or absent. Cache with a proactive timer, and log the expiry you computed.",
    },
    {
      where: "Under load",
      symptom: "\"Calls got slow, then we started getting throttled\"",
      cause:
        "A token fetched per request. One exchange should serve thousands of calls.",
    },
    {
      where: "Consent",
      symptom: "\"Biometrics is being demanded and we are not set up for it\"",
      cause:
        "Facility context missing or wrong, so the facility's authentication policy resolved to the strict default.",
    },
    {
      where: "Eligibility",
      symptom: "\"The benefit list is empty for a patient who is definitely covered\"",
      cause:
        "Benefits are filtered by facility empanelment. The wrong facility gives you an empty list, and nothing in the error mentions facilities.",
    },
    {
      where: "Bill",
      symptom: "\"The price is wrong, and it is wrong consistently\"",
      cause:
        "Tariff variants are facility-scoped. A stale or hard-coded facility code prices every line against the wrong contract.",
    },
    {
      where: "Submit",
      symptom: "\"The claim will not send and we cannot see why\"",
      cause:
        "No delivery endpoint at all, neither a registered callback nor an X-Callback-Url header on the request. Submission will not proceed without somewhere to send the decision.",
    },
    {
      where: "Three weeks after go-live",
      symptom: "\"We are live and no money has arrived\"",
      cause:
        "The banking record was never completed. A human reviews it, and it gates every payment regardless of how many claims were accepted.",
    },
  ]}
/>

One pattern accounts for most of that list. Credentials get treated as setup and are then never
looked at again: a token with no logged expiry, a facility code nobody re-reads, a callback
registered in one environment. None of the three shows up until a patient is waiting.

### Errors

<ErrorDictionary stop="authenticate" />

## What carries forward

<Wire
  rows={[
    { call: "access_token", does: "Every stop from 01 to 08 takes it as a header. Nothing on the rail works without it.", keep: "Refresh before it dies" },
    { call: "Facility headers", does: "They scope every answer you get. The same call from two facilities gives you two different answers.", keep: "Set once in the client" },
    { call: "A place to deliver decisions", does: "Checked at 06 · Preauthorize and 08 · Submit. Register an endpoint here and the check is invisible; override it per request with X-Callback-Url where you need to.", keep: "Per environment" },
  ]}
/>

There is no `next_action` at this stop, because nothing patient-shaped has happened yet. You
are just ready to begin.

**Next:** [01 · Identify](/rail/stops/Identify). With a token and a facility, you can resolve
who is in front of you.

<AgentPrompt title="Build Authenticate with an agent" filename="authenticate.instructions.md">{`You are integrating an HMIS with the Savannah unified payer rail.

Task: implement stop 00, Authenticate. This stop establishes two things: who your
system is, and which facility it is calling from.

TOKEN
  Exchange the client id and secret for an access token, server-side only.
  Read expires_in from the response and compute an absolute expiry.
  Cache the token. Refresh proactively on a timer at roughly 80% of its life.
  Do NOT refresh reactively on a 401: that turns one slow call into two while a
  patient is waiting.
  Never log the token, never place it in a URL, never ship the secret to a
  browser or mobile client.

FACILITY CONTEXT
  You are one system acting for many facilities. The token identifies you as the
  vendor; the facility headers say which site the current work belongs to, and
  they decide almost every downstream rule.
  Configure one HTTP client that attaches on every request:
    Authorization: Bearer <token>
    X-Facility-Id: <facility code>
    X-Facility-Id-Type: <scheme>
  Resolve the facility from the session or tenant rather than from configuration.
  A hard-coded code survives a single-site pilot and then misprices everything
  once a second site is live.
  Set these in the client, not at call sites. A facility identifier must never
  appear in a request body.
  Treat facility context as required on every call, not only the first.

CALLBACKS
  Preauth and claim decisions are asynchronous, so the rail needs a delivery
  target. There are two routes and they compose:
    - Register an endpoint for preauth.decision, claim.decision and
      remittance.posted, and persist the returned callback_id. This is the
      default for every call that says nothing.
    - Send X-Callback-Url: <url> on an individual request to have that
      request's decision delivered elsewhere.
  Register the default before building later stops: submission will not proceed
  with no delivery target at all.

OPERATIONAL RULES
  - Log the computed token expiry, or a 401 will be impossible to account for
    later.
  - One token exchange should serve thousands of calls. Per-request exchange
    will be throttled.
  - Register callbacks per environment; a sandbox registration does not carry
    to production. The same applies to any URL you send in X-Callback-Url.
  - Complete the banking record early. It is human-reviewed and gates payment
    no matter how many claims are accepted.

WHAT FAILS ELSEWHERE IF THIS IS WRONG
  Missing or wrong facility context does not fail here. It surfaces as an empty
  benefit list at the cover check, as unexpected biometrics at Consent, and as
  mispriced lines at Bill.`}</AgentPrompt>

---

## /rail/stops/Bill

# 07 · Bill

  The claim grows as you bill. It is not assembled afterwards from memory.

## Why this stop exists

Everything done to the patient becomes a line under the visit. The claim is built
server-side as you go, so a line can be refused at the moment it is added rather than at
submission.

This is an interchange. The eTIMS branch leaves the rail here, carrying the tax invoice and
the patient's own share.

## Add a bill line

<ApiRef method="POST" path="/api/v2/visits/{visit_ref}/bill-lines" to="/rail-api/07-bill" keep="bill_line_ref">
  Charge under an authorized service line. Name the line via `service_line_ref`; the payer
  answers with what it covers and the patient's copay.
</ApiRef>

A bill line is **payer-first**: the rail sets the charge on the payer's system, and the
payer's answer — the covered amount and the patient's copay — is what gets persisted. The
line names a `service_line_ref` (from [04 · Visit](/rail/stops/Visit)), and through it the
cover, so the charge and the authorization it draws down cannot be paired inconsistently.

```json
{
  "code": "SHA-18-005",
  "name": "Consultation, outpatient",
  "quantity": "1",
  "amount": "1500.00",
  "service_line_ref": "85ecfa5e-…",
  "practitioner_ref": "47d8e845-…"
}
```

<Wireframe
  title="Add a charge"
  actor="Billing"
  rows={[
    [
      { label: "Item", kind: "field", span: 2, from: "code + name" },
      { label: "Amount", kind: "field", span: 1, from: "amount" },
      { label: "Add", kind: "action", span: 1 },
    ],
    [
      { label: "Covered KES 1,200 · patient owes KES 300", kind: "text", span: 4, tone: "positive", from: "the payer's answer", note: "The copay is the payer's number; the patient's share is a consequence, not a declaration." },
    ],
  ]}
  caption={<>A line with no <code>service_line_ref</code> is self pay in full — no payer is asked, so it records even during a payer outage.</>}
/>

The covered and owed amounts are the payer's, never computed here. A refused line comes back
`not-billable` with the payer's verdict relayed; an unreachable payer keeps the charge
`planned` and answers `PAYER_UNREACHABLE` (502), safe to retry.

## Lines that wait

An item requiring preauthorisation comes back `held` with `next_action: preauth_pending`
instead of `none`. It sits visibly on the bill while every other line proceeds. Approval at
the previous stop releases it without touching the rest of the invoice.

Show held lines in your billing UI. A biller who cannot see what is waiting will assume it
failed and add it again.

## Combination rules run per line

Some codes cannot sit on the same visit together. The check runs on **every add-line call**,
so the biller finds out at once:

```json
{
  "error": "INVALID_CODE_COMBINATION",
  "message": "SHA-12-001 (Outpatient consultation) cannot be billed alongside SHA-07-SC-01 (Inpatient) on the same visit day.",
  "conflicting_codes": ["SHA-12-001", "SHA-07-SC-01"],
  "path": "lines[].billing_code",
  "fix_stage": "billing"
}
```

Order matters. A set of lines that is legal in one order can be refused in another, so where
your workflow permits, ask before adding rather than adding and handling the refusal.

## Documents travel with the line

Attach documents as they are captured rather than in a scramble at the end. The
`requiredDocuments` list you read at eligibility is what pre-flight checks by name at Submit.

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/documents" to="/rail-api/07-bill">
  Attach a document against the visit, keyed by the document type the item requires.
</ApiRef>

  `POST /api/v1/visits/{visit_id}/level-changes` is not a registered route. The rule below is the
  one the rail is being built to; the call to make it with does not exist today.

## Accommodation and level changes

The platform generates per-diem lines itself: days multiplied by the correct tariff. Your own
day count is a cross-check rather than the source. The day of admission is day one whatever
the hour, and the counter increments at midnight.

When a patient moves between levels of care, the old line is **retired and a new one starts**,
rather than being edited in place:

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/level-changes" to="/rail-api/07-bill">
  Move a per-diem line to a different level of care from a point in time.
</ApiRef>

Nothing is ever deleted. A wrong line is retired with a reason and a fresh one created, so
the audit trail behind a benefit's balance survives every correction.

## The price is not always the gazetted tariff

The level tariff you read at eligibility is only the default. Where a facility has a
**negotiated contract** with a payer, the negotiated rate applies instead. It is the largest
pricing error an integrator can make today without noticing, because a wrongly priced line
looks no different from a correct one.

<ApiRef method="GET" path="/api/v1/tariffs" to="/rail-api/07-bill">
  The price that actually applies: the gazetted level tariff, or the negotiated rate where a contract exists.
</ApiRef>

Read `source` before you read the number. It takes three values, and each one means something
different for your pricing:

<Wire
  rows={[
    { call: "GAZETTED", does: "The published level tariff applies. What you read on the procedure is what you bill.", keep: "applicable_tariff" },
    { call: "NEGOTIATED", does: "This facility has a contract for this scheme, and the level rule does not apply. Quoting the gazetted figure underbills or overbills every line.", keep: "applicable_tariff, contract_reference" },
    { call: "BILL_TO_BALANCE", does: "Public-officer covers can be billed above the tariff, against the member's balance. The tariff is not a ceiling here.", keep: "applicable_tariff, balance" },
  ]}
/>

  On most covers the tariff is the ceiling. On public-officer add-on covers the balance is the
  ceiling instead, and a provider may bill above the gazetted rate up to what the member has left.
  An integration that clamps every line to the tariff quietly under-recovers on the covers where
  there is most to recover.

## What a facility level may bill at all

Level decides more than price. Some work cannot be billed at some levels at all, and the refusal
arrives at the line rather than when the item is chosen.

<Wire
  rows={[
    { call: "Level 2", does: "Primary care, basic laboratory, maternity and outpatient public-officer services only. No per diem, no dialysis, no major surgery.", keep: "—" },
    { call: "Level 3 and above", does: "Per diem becomes billable.", keep: "—" },
    { call: "Level 4 and above", does: "Dialysis becomes billable.", keep: "—" },
    { call: "Levels 5 and 6", does: "Emergency-fund claims can only be started here.", keep: "—" },
    { call: "Level 6", does: "Everything except primary care.", keep: "—" },
  ]}
/>

Read the level from the facility registry rather than storing it, and filter what you offer by it.
A picker that lists dialysis at a level 3 site produces a rejection, after a clinician has already
spent time on it.

## Per diem counts days, and the rules are strict

Per diem has its own arithmetic rather than being a daily version of fee-for-service, and most of
the mistakes are in the counting.

<BuildSequence
  steps={[
    { do: "Day of admission is day one", detail: "Regardless of the time of day. A patient admitted at 23:40 has used a day." },
    { do: "The counter increments at midnight", detail: "Not on a rolling 24 hours. Two calendar days is two days even if it is ten hours." },
    { do: "Same-day admission and discharge is rejected", detail: "There is no zero-night per-diem claim. If the stay did not cross midnight, it is not this payment mechanism." },
    { do: "Per diem cannot be mixed with a surgical package", detail: "Choose one. The combination is refused, and the refusal names codes rather than mechanisms." },
    { do: "A per-diem line cannot be removed once added", detail: "Correcting it means correcting the visit, not deleting the line. Add it deliberately." },
  ]}
/>

Length-of-stay caps are per benefit, and some are **per household per year** rather than per visit,
so a relative's admission can shorten what this patient may claim.

## Surgery carries a global period

A surgical claim covers a window of care rather than a single act, and inside that window some
rebates cannot be billed at all.

<Wire
  rows={[
    { call: "Minor surgery", does: "One night", keep: "global period" },
    { call: "Major surgery", does: "Three nights", keep: "global period" },
    { call: "Specialised surgery", does: "Seven nights", keep: "global period" },
  ]}
/>

Inside the global period, **medical inpatient, critical care, mental health and palliative rebates
cannot be billed.** Beyond it, further nights are billed at the gazetted rebate rate and the
admission has to be updated to a complication. Admission, procedure and discharge dates are all
required on a surgical claim.

Two things can still be claimed separately: an **unplanned return to theatre**, and care unrelated
to the original procedure. The claim has to be able to tell them apart, so do not fold either one
into the original line.

  Moving a patient between inpatient and critical care, or inpatient and palliative, and back again,
  is allowed, and each period is priced at its own tariff. The admission is not one stay at the
  higher rate. If your billing model holds a single rate for the admission, switching will misprice it.

## Money is held as you bill

<Wire
  rows={[
    { call: "held", does: "Committed against the benefit, visible on the working ledger", keep: "reservation_id" },
    { call: "consumed", does: "The claim was submitted, so the hold became actual spend", keep: "—" },
    { call: "released", does: "The line was retired or the visit cancelled, and the amount went back to the benefit", keep: "—" },
    { call: "expired", does: "The reservation outlived its maximum age", keep: "—" },
  ]}
/>

  Not every payer holds money in a ledger you can see. Where balances are tracked externally,
  what you read as an available balance is a live read of the payer's own figure rather than
  a local reservation. The contract you code against is the same either way: read
  `reservation_id` off the line if it is there, and do not build logic that assumes it always
  will be.

## Every line carries its scheme code

A claim line is billed against a fund, and the **scheme code on the line is what routes it there.**
Lines on one visit can legitimately carry different scheme codes, because a member's covers differ
by benefit and the cover can be chosen per item.

Treat it as required on every line rather than as an override you occasionally set. A missing or
wrong scheme code routes the line to the wrong fund, and comes back looking like an assessment
dispute rather than a routing mistake.

## Diagnoses, prescriptions and switching

These three rules reject claims and are easy to miss.

<Wire
  rows={[
    { call: "One primary diagnosis per procedure", does: "Not one per claim. A standard claim needs at least one primary diagnosis against each procedure, and duplicate codes on the same claim are rejected.", keep: "the diagnosis per line" },
    { call: "Primary care takes exactly one", does: "Two primary diagnoses on a primary care claim is a rejection, and the diagnosis catalogue is filtered to primary-care-applicable codes for those claims.", keep: "—" },
    { call: "Prescriptions come from the national catalogue", does: "Dispensed quantity cannot exceed prescribed quantity, and some visit types exclude prescriptions entirely.", keep: "the catalogue code" },
  ]}
/>

**Switching between levels of care is priced per period.** Moving a patient from inpatient to
critical care and back, or inpatient to palliative, is allowed, and each period is priced at its own
tariff rather than the whole stay at the higher one.

  A few of these, prescription and diagnosis rules on primary care claims in particular, may
  currently be enforced in the interface rather than in the API. An integration that does not use
  that interface is not stopped today, and would start failing when the check moves. Build to the
  rule rather than to what the environment currently lets through.

## What breaks here

<CostTable
  rows={[
    {
      where: "Bill",
      symptom: "\"The line was refused and the codes look fine individually\"",
      cause: "A combination rule. The conflict is with another line already on the visit, and the message names both.",
    },
    {
      where: "Bill",
      symptom: "\"The price came back different from our price list\"",
      cause: "The rail resolves pricing from tariff, facility level and cover rather than from what you sent. Your price list is for your own invoice, not this one.",
    },
    {
      where: "Bill",
      symptom: "\"We cannot edit the accommodation line\"",
      cause: "Per-diem lines are retired through a level change, never edited. Editing is not a supported operation.",
    },
    {
      where: "Submit",
      symptom: "\"Unmapped code\"",
      cause: "The item was never declared in mapping, so it has no path to a payer revenue code. Anything undeclared stays off the claim entirely.",
    },
  ]}
/>

<CostTable
  rows={[
    {
      where: "Reconciliation",
      symptom: "\"Every line at this facility is paid at a different amount than we billed\"",
      cause:
        "A negotiated contract exists and the gazetted level tariff was used. Read source from the tariff call before pricing anything.",
    },
    {
      where: "Reconciliation",
      symptom: "\"We under-recovered on the public-officer covers\"",
      cause:
        "Lines were clamped to the tariff. On those covers the balance is the ceiling, not the tariff.",
    },
    {
      where: "Bill",
      symptom: "\"Dialysis was refused and the code is right\"",
      cause:
        "Facility level. Dialysis is level 4 and above; per diem is level 3 and above. The picker offered something the site cannot bill.",
    },
    {
      where: "Bill",
      symptom: "\"The per-diem claim was rejected for a same-day discharge\"",
      cause:
        "There is no zero-night per diem. The day of admission is day one and the counter moves at midnight.",
    },
    {
      where: "Bill",
      symptom: "\"We cannot bill the ICU days inside the surgical window\"",
      cause:
        "Global period. Critical care, medical inpatient, mental health and palliative rebates are excluded for one, three or seven nights depending on the surgery.",
    },
  ]}
/>

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 422 | `UNMAPPED_CODE` | The code does not resolve to a live, mapped item. |
| 422 | `INVALID_CODE_COMBINATION` | The line conflicts with another active line. |
| 409 | `LINE_NOT_RETIRABLE` | Retire attempted on a per-diem line outside a level change. |
| 409 | `RESERVATION_EXCEEDED` | The amount exceeds what is available at the moment of the call. |

## The branch leaves here

Billing produces obligations the payer never sees: the tax invoice, and whatever the
patient pays themselves. Those leave the rail at this stop:

- **[Invoice · eTIMS](/docs/eTIMS/Getting-Started)**, for sending the tax invoice to KRA
- **[Collect · Slade Advantage](/docs/Slade-Advantage/Getting-Started)**, for taking the patient's share

## Next

**Next:** [08 · Submit](/rail/stops/Submit)

---

## /rail/stops/Consent

# 03 · Consent

  You send who, where and why. The rail picks the factor — fingerprint, face, one-time code,
  guardian or eKYC — runs it, and returns a proof. You never choose the factor, integrate a
  scanner, or branch per payer. Render what you are given, and keep the proof.

## What this stop does

Consent answers two things at once: is this really the person, and may this data be seen or this
action taken. One call does both. Which factor is legal — for this member, at this facility, on
this payer, for this purpose — is decided server-side and versioned there, so your code carries no
`if minor`, no `if whitelisted`, and no biometric vendor's name.

It stands on its own: you can ask for consent to read a record or check a cover without any claim
or visit existing.

## What you send

<ApiRef method="POST" path="/api/v2/patients/{unique_patient_id}/authentications" to="/rail-api/03-consent" keep="authentication_id + collection.url">
  Ask for an authentication. A thin body in, a decision and a next step out.
</ApiRef>

The subject is the patient in the path; the facility comes from the `X-Facility-Id` /
`X-Facility-Id-Type` headers. Neither is read from the body.

<Wire
  rows={[
    { call: "network", does: "Which payer network this is for. It selects the rules that apply and the conduit the factor runs on.", keep: "—" },
    { call: "purpose", does: "Why you are asking. It picks the rules and becomes the scope the proof may be spent on.", keep: "—" },
    { call: "agent_id", does: "Required. The national ID of the operator asking — the audit note for who requested it, not routing.", keep: "—" },
    { call: "callback_url", does: "Required. Where the outcome is delivered; a registered endpoint is used only when this is absent.", keep: "—" },
    { call: "selection_ref", does: "Optional. The cover in scope, from covers/select at 02.", keep: "—" },
  ]}
/>

Do not send hardware context — no workstation, agent or device identifiers. The collection UI
captures those from the machine that does the capture.

## What you get back — two shapes

Switch on `next_action`. Assuming there is always a URL hangs every code path; assuming there
never is strands every biometric capture.

<Wire
  rows={[
    { call: "next_action: collect", does: "A strong factor was chosen. You get status pending and a collection.url — embed it, and everything the member sees and does happens inside it: factor choice, capture, retries, fallbacks.", keep: "collection.url" },
    { call: "next_action: await_callback", does: "A one-time code was dispatched. Status pending, nothing to render — show a 'code sent' state and wait.", keep: "authentication_id" },
  ]}
/>

  Where the deployment knows its public address, `collection.url` is absolute — scheme, host and
  gateway prefix included, with the single-use launch code already on it. Use it as the iframe
  `src` exactly as given; prefixing a base URL produces a doubled host and a frame that never
  loads, and opening it from a REST client burns the single-use code.

## The outcome

Read the record for the result — never treat the capture window closing as success. A push arrives
on your `callback_url`; poll this only as the safety net.

<ApiRef method="GET" path="/api/v2/patients/{unique_patient_id}/authentications/{id}" to="/rail-api/03-consent" keep="status + expires_at">
  Read the authentication back.
</ApiRef>

<Wire
  rows={[
    { call: "pending", does: "Dispatched or awaiting capture. Not a failure, not something to retry.", keep: "—" },
    { call: "verified", does: "The factor succeeded. A freshness window starts at verified_at.", keep: "expires_at" },
    { call: "failed", does: "Terminal. Raise a new authentication rather than retrying this one.", keep: "the reason" },
  ]}
/>

Consumption and expiry are not statuses: whether a proof can be spent is decided when you spend it.
Attempt the redemption and handle the refusal rather than branching on a status.

## Purpose is the scope

Purpose picks which rules run and bounds what the proof may later be spent on.

<Wire
  rows={[
    { call: "eligibility_check", does: "Confirm cover, run an eligibility search.", keep: "—" },
    { call: "cover_view", does: "View benefit or cover detail.", keep: "—" },
    { call: "visit_start", does: "Open a visit, begin care.", keep: "—" },
    { call: "visit_end", does: "Close a visit or discharge. Always needs its own authentication.", keep: "—" },
    { call: "pii_access", does: "Read a patient summary or clinical record.", keep: "—" },
  ]}
/>

## A proof is a resource, not an event

A verified authentication is persisted, has a freshness window, and — depending on the factor —
can be spent more than once. Keep the `authentication_id`, not just the fact that it worked.

<Wire
  rows={[
    { call: "Strong factors", does: "A fingerprint or eKYC verification backs several intents while fresh — an eligibility search and, later, opening the visit. Do not re-authenticate defensively.", keep: "authentication_id" },
    { call: "Weak factors", does: "A one-time code is spent once; a second redemption is refused.", keep: "—" },
    { call: "Standalone purposes", does: "Some are never satisfied by an existing proof. Closing a visit is one — always take a fresh authentication.", keep: "a fresh one" },
  ]}
/>

  If the proof that opened a visit could also close it, a facility could release a patient while the
  visit stays open and keeps accruing inpatient days. Closing is standalone by rule.

## Sensitive data is rendered, not fetched

For clinical reads the flow inverts: never fetch the record into your client and then ask for
consent. Consent produces a single-use view token, you embed a viewer, and the data streams into
that frame. Your application never holds the payload, and the token is burned on read — to show the
same record twice, ask twice (cheap when a fresh proof exists).

## Inside the hosted surface

You do not call these in a normal integration — the surface renders inside the iframe and the
browser posts to them. They are here because test harnesses drive the surface headlessly, and the
failure below looks like a bug in your code when it is not.

<ApiRef method="POST" path="/api/v1/ui/consent/otp/send" to="/rail-api/03-consent" keep="the re-rendered verify slot">
  Send the passcode for the launched authentication. Form-encoded in, HTML fragment out.
</ApiRef>

<ApiRef method="POST" path="/api/v1/ui/consent/otp/verify" to="/rail-api/03-consent" keep="the receipt fragment">
  Check the code the member read back. A refusal re-renders the slot with the executor's own message.
</ApiRef>

Both take `authentication_id`, `contact_id`, `unique_patient_id`, `purpose`, `selection_ref`,
`callback_url` (and `verify` adds `otp`). The surface re-runs the consent decision on every post,
so the whole context must travel with each one. The session and tenant come from the `hie_session`
cookie and an `X-Csrf-Token` header (echoing `hie_csrf`), both scoped to the UI mount path.

  Both endpoints answer `200` on failure, with the message inside the HTML fragment, so an htmx
  swap still lands and the member sees the sentence. There is no status code to branch on — read the
  fragment. (On a test deployment the send response includes the passcode inline; production never
  does, so never read the code out of the fragment.)

## Age and guardian

<Wire
  rows={[
    { call: "Under 7", does: "No fingerprint. The guardian consents; the code goes to the guardian.", keep: "guardian identity" },
    { call: "7 to 17", does: "Prints enrolled at the point of care, then verified; else the guardian's code.", keep: "guardian identity" },
    { call: "18 and over", does: "The member verifies; the code goes to the member.", keep: "member contact" },
  ]}
/>

Guardian consent is a modifier on the underlying factor and inherits its strength — a guardian's
fingerprint is strong, a guardian's code is weak. The record carries who consented and on whose
behalf.

  Phone numbers must be in Kenyan format — a bad number does not error, the code simply never
  arrives. And the whitelist reason list is not yet unified across systems: send the closest match,
  keep your own record of what the operator chose, and do not build a picker on values you cannot
  confirm.

## Break-glass

When someone arrives unable to consent and care cannot wait, there is a traced exception: the
practitioner authenticates to their own identity (only ones the health worker registry knows may do
it) and gives a reason from a constrained list plus a narrative. Skip it and the rest of the journey
does not work — the ambulance leg cannot be claimed and the patient cannot be handed over. Build the
path, and make it look exceptional in your interface.

## Which factors a facility offers

Resolved for you, but the resolution explains most "the scanner is broken" tickets.

<Wire
  rows={[
    { call: "Facility enforces biometrics", does: "The normal case — fingerprint first, code where the member qualifies.", keep: "—" },
    { call: "Facility de-enforced", does: "The one-time code becomes available to EVERY patient there, whitelisted or not.", keep: "—" },
    { call: "Member individually whitelisted", does: "The code path for this person, at any facility.", keep: "—" },
  ]}
/>

Biometric no-match is normal (~3 adults in 10); the embedded UI falls back to the code path and
raises a whitelist request where needed. Do not build a retry loop around the reader.

## What breaks here

<CostTable
  rows={[
    {
      where: "One-time code path",
      symptom: "\"The integration hangs waiting for a URL that never arrives\"",
      cause: "A weak factor returns next_action await_callback with nothing to render. Switch on next_action.",
    },
    {
      where: "Embedded frame",
      symptom: "\"The frame loads with a doubled host and never renders\"",
      cause: "collection.url is absolute. Use it as the iframe src verbatim — do not prefix a base URL.",
    },
    {
      where: "OTP surface (harness)",
      symptom: "\"'unique_patient_id is required' but we got a 200\"",
      cause: "The hosted OTP endpoints answer 200 on failure with the message in the fragment. Read the fragment, not the status.",
    },
    {
      where: "Any sensitive view",
      symptom: "\"The record was on the client before consent was granted\"",
      cause: "Data was fetched, then permission asked. Ask first, render inside the viewer, never hold the payload.",
    },
    {
      where: "Every capture",
      symptom: "\"We ask for a fingerprint twice in one visit\"",
      cause: "A strong proof was treated as an event. A fresh one backs several purposes — keep authentication_id and spend it.",
    },
    {
      where: "Discharge",
      symptom: "\"The proof from admission is refused at discharge\"",
      cause: "Closing a visit is standalone. No proof taken for another purpose satisfies it.",
    },
    {
      where: "Outcome",
      symptom: "\"We showed consent as granted and the claim was rejected for no authorisation\"",
      cause: "The frame closing was treated as the answer. Only the record read or the signed callback establishes consent.",
    },
  ]}
/>

## Next

**Next:** [04 · Visit](/rail/stops/Visit)

<AgentPrompt title="Build consent with an agent" filename="consent.instructions.md">{`You are integrating an HMIS with the Savannah unified payer rail.

Task: implement stop 03 (Consent). You do NOT choose the authentication factor. You ask for
an authentication, the rail decides and executes the factor, and you spend the proof.

REQUEST
  POST /api/v2/patients/{unique_patient_id}/authentications
  The subject is the patient in the PATH. The facility comes from the X-Facility-Id and
  X-Facility-Id-Type headers. Neither is read from the body.
  Body:
    network       the payer network
    purpose       eligibility_check | cover_view | visit_start | visit_end | pii_access
    agent_id      REQUIRED; the national ID of the operator asking. An audit note, not routing.
    callback_url  REQUIRED; a registered endpoint is used only if this is absent
    selection_ref optional; the cover in scope, from 02 · Verify cover
  Do NOT send hardware context: no workstation, agent or device identifiers. Those are
  captured by the collection UI from the machine that performs the capture.
  Do NOT send a list of factors or methods. Which factors are legal is resolved server-side
  from the member, the facility, the payer and the purpose.

RESPONSE: TWO SHAPES, SWITCH ON next_action
  next_action = await_callback : a one-time code was dispatched. Nothing to render. Wait.
  next_action = collect        : embed collection.url. It is ABSOLUTE where the deployment
                                 knows its public address — do not prefix a base URL onto
                                 it, or you get a doubled host. Everything the member sees
                                 and does happens inside it: factor choice, capture,
                                 retries, fallbacks. None of it reaches your code.
                                 Do not open it from a REST client: the code is single-use.
  Assuming either shape is always the one you get is the commonest bug here.

THE PROOF IS A RESOURCE, NOT AN EVENT
  Persist the authentication id, not merely "it succeeded".
  Strong factors (fingerprint, eKYC) can back SEVERAL purposes while fresh, so do not
  re-authenticate defensively; asking twice in one visit is a queue you created.
  Weak factors (one-time code) are spent once; a second redemption is refused.
  Standalone purposes can never be satisfied by an existing proof. Closing a visit is one:
  always raise a fresh authentication for it.
  Read expires_at from the record; do not assume a duration.

STATUSES
  pending | verified | failed. Failed is terminal, so raise a new authentication rather than
  retrying the old one.
  Consumption and expiry are NOT statuses. Whether a proof can be spent is decided at
  redemption, so attempt it and handle the refusal rather than branching on a status.

OUTCOME
  A push arrives on your callback_url; poll GET /api/v2/patients/{unique_patient_id}/
  authentications/{id} as the safety net, never as the primary path.
  Never treat the capture window closing as success. Read the record.

OTHER RULES
  Guardian consent is a modifier on an underlying factor and inherits its strength.
  Under 18 the guardian consents and receives the code; 18 and over the member does.
  Biometric no-match is a NORMAL outcome: roughly three adults in ten do not match. The
  code path is a main path with its own screens, not an error handler.
  Model at least two authentications per encounter: opening the visit and closing it.`}</AgentPrompt>

---

## /rail/stops/Entitle

# 02 · Verify cover

  This is where an identified person becomes a claim someone will pay. The answer is not a yes or a
  no; it is a named cover, plus the items that cover will pay for at this facility today.

## What this step is

[01 · Identify](/rail/stops/Identify) told you who is in front of you. This step answers the money
question, and it asks two separate questions to do it. Do not run them together.

<Wire
  rows={[
    { call: "Which cover pays?", does: "A member holds covers, plural. Someone has to say which one today's visit runs against, and that choice has to be visible rather than guessed.", keep: "the selected cover" },
    { call: "What does it pay for?", does: "Benefits, then categories, then procedures, each with an access point, a payment mechanism, whether it needs preauthorisation, and a balance.", keep: "procedure code" },
  ]}
/>

Keeping them separate is what stops a member with nine active covers waiting on nine balance checks
before anyone has asked which one they are using.

They are also ordered. Coverage, meaning whether this member is paid up and current, is settled
first by the systems that handle contributions. Only then is it worth asking what a cover
makes available here. Calling both at once, or reading the second before the first has answered,
produces a benefit list you cannot trust.

The rule that makes it work is that a person is not covered. A person holds covers, and exactly
one of them pays for this visit.

Two things are worth knowing before the detail starts, because they decide how much of this you
have to build yourself.

<Wire
  rows={[
    { call: "Your part is small", does: "List the covers, let a person choose one, send the choice back. Which fund pays, which tariff applies, whose balance is read and how the claim is assessed are all the rail's problem.", keep: "one call" },
    { call: "Nothing here is final", does: "The cover chosen at visit start is a default. It can be changed per item and changed again until the request is submitted.", keep: "room to correct" },
  ]}
/>

Both are expanded below, under [what you are responsible for](#the-multiple-cover-case) and
[when the choice becomes final](#when-the-cover-choice-becomes-final). If you read nothing else on
this page, those two sentences are the ones that change how you build.

### The four moves

There are four of them, and the split between the first two is the part that matters most.

<BuildSequence
  steps={[
    {
      do: "List the covers",
      detail: (
        <>
          Every scheme this member can use here, with who contributes to it and how long it
          runs. It is light enough to render a chooser without waiting on{" "}
          <a href="/rail-api/02-verify-cover">balances</a>.
        </>
      ),
    },
    {
      do: "Select one, visibly",
      detail: (
        <>
          An operator chooses. <strong>Do not auto-select silently.</strong>{" "}
          This is a financial decision, and nobody can audit a choice they cannot see.
        </>
      ),
    },
    {
      do: "Walk down to a billable service",
      detail:
        "Benefit, then category, then procedure. The procedure is the unit that carries the access point, the payment mechanism and the preauthorisation flag.",
    },
    {
      do: "Check the balance where there is one",
      detail: (
        <>
          Many benefits are not balance-tracked, so there is often nothing to check and that is
          normal. Where a figure does exist,{" "}
          <a href="/rail-api/02-verify-cover">read it</a> before quoting an amount, because
          limits can apply to the whole household rather than this member, so one that looks
          generous may already be partly spent.
        </>
      ),
    },
  ]}
/>

None of that is a gate. A missing balance does not block care and rarely blocks a claim. It means
this benefit is not tracked that way. Read it when it is there, say so plainly when it is not, and
carry on.

If you only remember one thing: <u>the cover is chosen once, explicitly, and everything
priced afterwards hangs off that choice.</u>

### What it looks like at the desk

Three ways to look at the step: the screens, the sequence and the branch points.

<Wireframe
  title="Member covers"
  actor="Front desk · after Identity"
  rows={[
    [
      { label: "This member is covered", kind: "field", tone: "positive", span: 4, from: "coverage.status", note: "One banner for the whole member. Below it, one row per cover." },
    ],
    [
      { label: "Jubilee Health · active", kind: "text", swatch: 1, span: 2, from: "payer, scheme, category", note: "A private insurer. Member demo-20-1234-00 · category demo-20-CAT A · relationship SPOUSE" },
      { label: "Until Feb 20, 2042", kind: "text", swatch: 1, span: 1, from: "validity" },
      { label: "Use this cover", kind: "action", span: 1 },
    ],
  ]}
  caption={<>The simple case, and also the common one: one usable cover, selected and carried forward. The banner is the verdict on the member, and the row beneath it is the cover that will pay.</>}
/>

The same screen when nothing pays.

<Wireframe
  title="Member covers"
  actor="Front desk · after Identify"
  rows={[
    [
      { label: "This member is not covered", kind: "field", tone: "negative", span: 4, from: "coverage.status", note: "Red banner, and it never appears on its own" },
    ],
    [
      { label: "Contributions not up to date", kind: "field", tone: "attention", span: 2, from: "coverage.reason", note: "Why, in the payer's words" },
      { label: "Member may pay via the payer portal or USSD, then retry", kind: "field", tone: "attention", span: 2, from: "coverage.message", note: "What the member can do about it, right now" },
    ],
    [
      { label: "Continue as cash", kind: "action", span: 2, note: "The identity is still resolved. Care is still possible." },
      { label: "Retry coverage check", kind: "action", span: 2, note: "After the member pays. Nothing needs re-identifying." },
    ],
  ]}
  caption={<>A red banner is not the end of the encounter. The patient exists and is identified, only the money has failed, and the response carried both the reason and a remedy.</>}
/>

With a cover chosen, the step continues downward: benefits, then categories, then the billable unit.

<Wireframe
  title="Available categories"
  actor="Clinical user · cover selected"
  rows={[
    [
      { label: "Search", kind: "field", span: 3, note: "These lists are long. A picker without search is unusable at a desk." },
      { label: "Filter by access point", kind: "field", span: 1, from: "access_point", note: "OP · IP · both" },
    ],
    [
      { label: "Inpatient services · SHA-07-SC-01", kind: "text", swatch: 2, span: 2, from: "sub_benefit_code", note: "National scheme. SHA calls this a sub-package." },
      { label: "Inpatient only", kind: "text", swatch: 2, span: 1, from: "access_point", note: "Choosing this inside an outpatient visit fails at Bill, not here" },
      { label: "View procedures", kind: "action", span: 1 },
    ],
    [
      { label: "Inpatient · PMF-07-SC-01", kind: "text", swatch: 3, span: 2, from: "sub_benefit_code", note: "Employer fund, same shape, different pot" },
      { label: "Inpatient only", kind: "text", swatch: 3, span: 1, from: "access_point" },
      { label: "View procedures", kind: "action", span: 1 },
    ],
    [
      { label: "Outpatient consultation · JUB-OP-01", kind: "text", swatch: 4, span: 2, from: "sub_benefit_code", note: "Private insurer. Its catalogue holds services and items, not interventions." },
      { label: "Outpatient", kind: "text", swatch: 4, span: 1, from: "access_point" },
      { label: "View services", kind: "action", span: 1 },
    ],
  ]}
  caption={<>Access point is what catches people on this screen. An inpatient-only category selected during an outpatient visit is refused three stops later, and the error there mentions codes rather than access points.</>}
/>

<Wireframe
  title="Available procedures · Inpatient"
  actor="Clinical user"
  rows={[
    [
      { label: "Management of medical cases", kind: "text", swatch: 2, span: 1, from: "code", note: "SHA-07-001, an intervention in SHA's vocabulary" },
      { label: "IP", kind: "text", span: 1, from: "access_point" },
      { label: "Preauth: No", kind: "field", tone: "positive", span: 1, from: "needs_preauth", note: "A Yes here sends you to 06 · Preauthorize before anything may be done" },
      { label: "Per diem", kind: "text", span: 1, from: "payment_mechanism", note: "Priced per day, not per item" },
    ],
    [
      { label: "Management of medical cases", kind: "text", swatch: 3, span: 1, from: "code", note: "PMF-07-001, the same name on an employer fund, with its own tariffs" },
      { label: "IP", kind: "text", span: 1, from: "access_point" },
      { label: "Preauth: Yes", kind: "field", tone: "negative", span: 1, from: "needs_preauth", note: "The same clinical work, gated differently by a different pot" },
      { label: "Fee for service", kind: "text", span: 1, from: "payment_mechanism" },
    ],
    [
      { label: "Select", kind: "action", span: 2, note: "This is the unit everything later prices against" },
      { label: "View balance", kind: "action", span: 2, note: "Do this before promising anything to the patient" },
    ],
  ]}
  caption={<>Four attributes decide how the rest of the encounter behaves: the code, the access point, whether preauthorisation is required, and how it is paid. The same clinical work can differ on all four between two funds, which is why the fund belongs on the row.</>}
/>

<Wireframe
  title="Procedure balance"
  actor="Clinical user · balance check"
  rows={[
    [
      { label: "Available to member: Yes", kind: "field", tone: "positive", span: 2, from: "available", note: "The answer the desk is waiting for" },
      { label: "Next available: Aug 13, 2026", kind: "text", span: 2, from: "next_available_on", note: "When a spent limit renews" },
    ],
    [
      { label: "Limits apply to: HOUSEHOLD", kind: "field", tone: "attention", span: 4, from: "limit_scope", note: "Not this member. A sibling's admission can exhaust this." },
    ],
    [
      { label: "Utilised: 22 visits · KES 11,237.80", kind: "text", span: 2, from: "utilisation" },
      { label: "Allocated / available: not applicable", kind: "text", span: 2, from: "allocated", note: "Per-diem procedures often carry no monetary ceiling. Absent is not zero." },
    ],
  ]}
  caption={<>Two fields on this screen cause most disputes: whose limit it is, and whether a blank means unlimited or unknown. Render both explicitly rather than defaulting them to zero.</>}
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    actor D as Front desk
    participant H as Your HMIS
    participant R as The rail
    participant P as Payer

    H->>R: Eligibility for this patient at this facility
    R->>P: Coverage and contribution status
    P-->>R: schemes[], one entry per scheme per contributor
    R-->>H: Member, covers, banner status
    D->>H: Selects one cover
    H->>R: Benefits for that cover
    R-->>H: Categories, filtered by access point
    H->>R: Procedures in the chosen category
    R-->>H: Codes, access point, preauth flag, payment mechanism
    H->>R: Balance for the chosen procedure
    R-->>H: Utilised, available, whose limit it is
    Note over H,R: Keep the cover selection and the procedure.<br/>Everything after this prices against them.
`} />

<Mermaid chart={`flowchart TD
    A["Identity resolved at 01"] --> B["Eligibility check"]
    B --> C{Any cover active?}
    C -- No --> D["Red banner + reason + remedy<br/>continue as cash, or retry after payment"]
    C -- Yes --> E["List every cover:<br/>scheme x contributor"]
    E --> F["Operator selects one, visibly"]
    F --> G["Benefit to category to procedure"]
    G --> H{Access point matches the visit?}
    H -- No --> I["Wrong category.<br/>Fails at Bill if it proceeds"]
    H -- Yes --> J{Balance available?}
    J -- No --> K["Show next available date.<br/>Check whose limit it is first"]
    J -- Yes --> L{Needs preauthorisation?}
    L -- Yes --> M["06 · Preauthorize before anything is done"]
    L -- No --> N["Carry on to 03 · Consent"]
`} />

## A member can hold many covers, and be a dependant on some of them

This is the part that surprises people, so it is worth stating plainly before any payload.

<Wire
  rows={[
    { call: "One payer, several schemes", does: "A single payer can grant more than one scheme at once, such as UHC and SHIF, with different windows and different rules.", keep: "one row each" },
    { call: "Several payers", does: "A member may hold covers from more than one payer: a national scheme, an employer scheme, a private insurer.", keep: "one row each" },
    { call: "Principal or dependant, per cover", does: "On some covers the member is the contributor. On others they are somebody's dependant, and both can be true of the same person on the same day.", keep: "memberType" },
  ]}
/>

So the list is a product rather than a set. There is one row per scheme, per contributor, which
means a member with three contributors across three schemes has nine rows, all of them valid.

  Without it, nine rows look like a duplication bug and an operator picks the first one. With it,
  the screen reads correctly: *SHIF, contributed by her employer* is a different cover from
  *SHIF, contributed by her father*, with a different policy number and a different balance.

`memberType` tells you which case you are in: `PRIMARY` when the member contributes,
`BENEFICIARY` when they are covered through someone else. On a beneficiary row,
`principalContributor` names the person whose cover it is, their relationship and their
employer. Store it with the encounter: every audit conversation about a dependant's claim opens
with "under whose cover?".

On screen, that looks like this.

<Wireframe
  title="Member covers"
  actor="Front desk · after Identify"
  rows={[
    [
      { label: "This member is covered", kind: "field", tone: "positive", span: 4, from: "coverage.status", note: "The verdict on the member. Every row beneath it is a separate cover." },
    ],
    [
      { label: "UHC · covered", kind: "text", swatch: 1, span: 2, from: "schemes[].schemeName", note: "Principal contributor: the member herself" },
      { label: "Until Sep 30, 2034", kind: "text", swatch: 1, span: 1, from: "coverage.endDate" },
      { label: "Use this cover", kind: "action", span: 1 },
    ],
    [
      { label: "SHIF · covered", kind: "text", swatch: 1, span: 2, from: "schemes[].schemeName", note: "Principal contributor: the member herself" },
      { label: "Until Sep 10, 2026", kind: "text", swatch: 1, span: 1, from: "coverage.endDate" },
      { label: "Use this cover", kind: "action", span: 1 },
    ],
    [
      { label: "SHIF · covered", kind: "text", swatch: 1, span: 2, from: "memberType: BENEFICIARY", note: "Same scheme, but the contributor is a parent. The member is a dependant on this one." },
      { label: "Until Sep 10, 2026", kind: "text", swatch: 1, span: 1, from: "coverage.endDate" },
      { label: "Use this cover", kind: "action", span: 1 },
    ],
    [
      { label: "TSC · covered", kind: "text", swatch: 1, span: 2, from: "schemes[].schemeName", note: "An employer scheme, contributed to by a parent. It has its own balances." },
      { label: "Until Jun 30, 2027", kind: "text", swatch: 1, span: 1, from: "coverage.endDate" },
      { label: "Use this cover", kind: "action", span: 1 },
    ],
    [
      { label: "Jubilee Health · active", kind: "text", swatch: 1, span: 2, from: "payer, scheme, category", note: "A private insurer. Member number demo-20-1234-00 · category demo-20-CAT A · relationship SPOUSE" },
      { label: "Until Feb 20, 2042", kind: "text", swatch: 1, span: 1, from: "validity" },
      { label: "Use this cover", kind: "action", span: 1 },
    ],
  ]}
  caption={<>Five rows for one person, all of them valid. The rows are uncoloured on purpose, because green belongs to the banner, which is the verdict on the member, rather than to the covers underneath it. What distinguishes a row is its payer and its contributor, so say those in words.</>}
/>

### There is no ranking, so do not build one

A member with several covers is not a puzzle with a correct answer. Pick any of them and you see
the benefits that cover supports. The covers frequently overlap, since the same eye-health benefit
can exist on two of them, so there is nothing to sort and no precedence to apply.

<Wire
  rows={[
    { call: "What choosing a cover does", does: "Scopes the benefit tree to what that cover supports. A different cover means a different tree, not a better or worse one.", keep: "the tree you get" },
    { call: "What it does not do", does: "It does not rank, exclude or consume anything. Selecting a cover is not spending it.", keep: "—" },
    { call: "Overlap is normal", does: "Two covers can both carry the same benefit, with different limits and tariffs. Neither is the right one in the abstract.", keep: "compare when it matters" },
  ]}
/>

So the chooser has one job, which is to show what each cover is and who contributes to it, then let
a person decide. Group rows by payer if that helps the eye, but do not pre-select across payers and
do not imply an order that the rail does not enforce.

  Which payer each row belongs to, and who contributes to it. A list of five schemes without those two
  facts cannot be used correctly by anyone, and the operator will pick the first row.

Two consequences follow from the same member holding several covers.

A dependant can be covered under more than one principal at the same time. A child whose mother
holds one public-officer fund and whose father holds another comes back with covers from both
households. One of them is used for a given item, and which one decides the tariff, the limits, the
required documents and the combination rules, so the choice is not cosmetic. Nor is it irreversible:
see [when the choice becomes final](#when-the-cover-choice-becomes-final).

Benefits are also filtered by member type. Principal, spouse and child see different things on the
same scheme: maternity is hidden from child dependants regardless of gender, and paediatric benefits
disappear at 18. The same scheme genuinely offers the mother and the child different sets, so do not
cache one member's benefit list and reuse it for a relative.

  What should happen when a member holds two covers with different validity windows, or one has
  expired, is not yet defined. Until it is, show both covers with their dates and let a person
  decide, rather than encoding a rule that may turn out to be wrong.

  A member may legitimately hold a public-officer cover that you cannot use. Empanelment is per
  facility, so if the site you are calling from is not empanelled for that fund, the cover comes back
  inactive with a reason, and its benefits are absent from the benefit list entirely.

  That is the correct answer rather than a fault, and it is why an empty benefit list is worth
  reading carefully. The member is covered, but this facility is not a place where that cover pays.
  Surface the reason on the row and let the operator select a different cover, rather than showing
  an unexplained empty list.

## The household behind the covers

A cover usually belongs to a household rather than to a person. That is where the extra covers on
the previous screen come from: a member appears on their own cover as principal, and on a relative's
cover as a dependant. One person, one day, two entries.

<Wireframe
  title="Household"
  actor="Front desk · principal's record"
  rows={[
    [
      { label: "Name", kind: "text", span: 1, note: "First name in full, the rest masked" },
      { label: "Registry identifier", kind: "text", span: 1, note: "unique_patient_id, masked" },
      { label: "Date of birth", kind: "text", span: 1 },
      { label: "Relationship", kind: "text", span: 1, from: "relationship" },
    ],
    [
      { label: "Margaret N***", kind: "field", tone: "positive", span: 1, from: "principal", note: "The contributor. Their cover is the one the others sit on." },
      { label: "CR46***334-2", kind: "text", span: 1 },
      { label: "12 Mar 1984", kind: "text", span: 1 },
      { label: "PRINCIPAL", kind: "text", span: 1 },
    ],
    [
      { label: "Charles G***", kind: "text", swatch: 1, span: 1 },
      { label: "CR36***771-2", kind: "text", swatch: 1, span: 1 },
      { label: "3 Aug 1981", kind: "text", swatch: 1, span: 1 },
      { label: "SPOUSE", kind: "text", swatch: 1, span: 1, note: "Also a contributor on a cover of their own" },
    ],
    [
      { label: "Esther W***", kind: "text", swatch: 1, span: 1 },
      { label: "CR54***778-8", kind: "text", swatch: 1, span: 1 },
      { label: "26 Aug 2002", kind: "text", swatch: 1, span: 1 },
      { label: "CHILD", kind: "text", swatch: 1, span: 1, note: "Adult child, still a dependant on this cover" },
    ],
    [
      { label: "Brian K***", kind: "text", swatch: 1, span: 1 },
      { label: "CR54***779-4", kind: "text", swatch: 1, span: 1 },
      { label: "14 Feb 2011", kind: "text", swatch: 1, span: 1 },
      {
        label: "CHILD",
        kind: "text",
        swatch: 1,
        span: 1,
        note: (
          <>
            A minor. Under 18s are{" "}
            <a href="/rail/stops/Identify#proving-it-is-the-same-person">
              verified differently
            </a>
          </>
        ),
      },
    ],
    [
      { label: "Faith W***", kind: "text", swatch: 1, span: 1 },
      { label: "CR54***780-1", kind: "text", swatch: 1, span: 1 },
      { label: "9 Sep 2015", kind: "text", swatch: 1, span: 1 },
      { label: "CHILD", kind: "text", swatch: 1, span: 1 },
    ],
    [
      { label: "Household limits are shared", kind: "field", tone: "attention", span: 4, note: "Where a limit applies to the household, all five draw on the same pool, and one admission can exhaust what another needs." },
    ],
  ]}
  caption={<>Five people, one cover. Two of them contribute to covers of their own, which is exactly why this member's cover list has more rows than they expect.</>}
/>

An empty household is also a real answer.

<Wireframe
  title="Household"
  actor="Front desk · principal's record"
  rows={[
    [
      { label: "Esther W***", kind: "text", span: 2, from: "principal", note: "Principal on her own cover" },
      { label: "CR54***778-8", kind: "text", span: 1 },
      { label: "Current member", kind: "text", span: 1, note: "Already selected" },
    ],
    [
      { label: "No listed dependants", kind: "field", tone: "attention", span: 4, note: "A real answer, not a failed fetch. Do not retry it, and do not render it as an error." },
    ],
  ]}
  caption={<>Reaching a dependant through a principal is covered at 01 · Identify. What matters here is that their spending may come out of the same limit as everyone else's.</>}
/>

## One cover, or several

Everything so far has assumed you pick a cover and move on. That is the common case and it is worth
stating separately from the harder one, because the two behave differently and the difference decides
who pays.

### The single-cover case

One usable cover. Select it, and it becomes the effective coverage for the encounter: a snapshot
of that cover taken at the moment of choosing, stored against the authorisation. Everything after it
resolves against that snapshot rather than re-reading the member's covers, including the benefits,
the balances, the tariffs, the preauthorisation and the claim.

Snapshotting matters because coverage is live data. A member's contribution status can change during
an admission; the encounter should not silently re-price itself when it does.

### The multiple-cover case

A member may hold several usable covers at once: their own, plus one or more where they are a
dependant on somebody else's. All of them may be valid, and only one pays for a given item.

<Wire
  rows={[
    { call: "Chosen at visit start", does: "The cover selected when the encounter opens becomes the PRIMARY cover. It is the default for everything billed under this visit.", keep: "effective coverage" },
    { call: "Changeable at billing", does: "When an item is billed, the operator can bill it against a different valid cover, typically one where the patient is a dependant and the benefit sits with that contributor.", keep: "the cover on that item" },
    { call: "Recorded per item", does: "Each billed item and preauthorisation carries the scheme it was raised under, so one encounter can legitimately draw on two contributors.", keep: "scheme_code, scheme_name" },
  ]}
/>

It helps to picture where you are by this point. The member was identified, a cover was chosen when
the visit opened, and care has happened. You are now in the billing workflow, adding items to a bill
or a preauthorisation, and the operator can be offered the same choice again, because the cover on
those items is still theirs to set.

<Wireframe
  title="The selected cover will be used for billing"
  actor="Billing · one member, two contributors"
  rows={[
    [
      { label: "Margaret N*** · PRIMARY COVER", kind: "field", tone: "positive", span: 2, from: "principal_cr_no + badge", note: "Chosen at visit start. Eye health KES 60,000 · Inpatient KES 1,829,936 · Outpatient KES 299,500" },
      { label: "Charles G***", kind: "text", swatch: 1, span: 2, from: "principal_cr_no", note: "Also valid. Balances load when selected, so empty here means unread rather than zero." },
    ],
    [
      { label: "Items on this bill", kind: "text", span: 4, note: "Every item below is billed under the selected cover unless it is given its own" },
    ],
    [
      { label: "Spectacle magnifiers · SHA-05-030", kind: "text", span: 2, from: "procedure" },
      { label: "KES 2,343", kind: "text", span: 1, from: "amount" },
      { label: "Margaret N*** · TSC", kind: "field", tone: "positive", span: 1, from: "scheme + contributor" },
    ],
    [
      { label: "Frames · SHA-05-034", kind: "text", span: 2, from: "procedure" },
      { label: "KES 8,000", kind: "text", span: 1, from: "amount" },
      { label: "Margaret N*** · TSC", kind: "field", tone: "positive", span: 1, from: "scheme + contributor" },
    ],
    [
      { label: "Consultation · SHA-12-004", kind: "text", span: 2, from: "procedure" },
      { label: "KES 1,500", kind: "text", span: 1, from: "amount" },
      { label: "Margaret N*** · TSC", kind: "field", tone: "positive", span: 1, from: "scheme + contributor" },
    ],
  ]}
  caption={<>The green card is the cover in force, and every item inherits it. Badge it explicitly: an operator who cannot tell which of two covers is active will not trust either.</>}
/>

Now the operator changes their mind, perhaps because this benefit has more left on the father's
cover, or because the mother's limit is nearly spent. They pick the other card.

<Wireframe
  title="The selected cover will be used for billing"
  actor="Billing · after switching cover"
  rows={[
    [
      { label: "Margaret N***", kind: "text", swatch: 1, span: 2, from: "principal_cr_no", note: "No longer in force. Still valid, still selectable." },
      { label: "Charles G*** · PRIMARY COVER", kind: "field", tone: "positive", span: 2, from: "principal_cr_no + badge", note: "Now in force. Balances loaded for this contributor: Eye health KES 45,000 · Inpatient KES 2,000,000" },
    ],
    [
      { label: "Items on this bill", kind: "text", span: 4, note: "Re-priced against the new cover, so the amounts moved and the screen says so" },
    ],
    [
      { label: "Spectacle magnifiers · SHA-05-030", kind: "text", span: 2, from: "procedure" },
      { label: "KES 2,100", kind: "field", tone: "attention", span: 1, from: "amount", note: "Was 2,343, because a different fund carries a different tariff" },
      { label: "Charles G*** · TSC", kind: "field", tone: "positive", span: 1, from: "scheme + contributor" },
    ],
    [
      { label: "Frames · SHA-05-034", kind: "text", span: 2, from: "procedure" },
      { label: "KES 8,000", kind: "text", span: 1, from: "amount", note: "Unchanged on this one" },
      { label: "Charles G*** · TSC", kind: "field", tone: "positive", span: 1, from: "scheme + contributor" },
    ],
    [
      { label: "Consultation · SHA-12-004", kind: "text", span: 2, from: "procedure" },
      { label: "KES 1,500", kind: "text", span: 1, from: "amount" },
      { label: "Charles G*** · TSC", kind: "field", tone: "positive", span: 1, from: "scheme + contributor" },
    ],
  ]}
  caption={<>The same bill, a different payer behind it. One call moved the effective cover, the items re-priced, and every line now names the contributor it will be assessed against.</>}
/>

One call makes that switch. You send the cover the operator chose against the encounter, and the
rail updates the effective coverage, which is what every later balance, tariff and assessment reads
from. See
[the effective-coverage call](/rail-api/02-verify-cover) in the reference.

  List the covers, let the person at the desk choose one, and send that choice back. That is the
  whole of your responsibility for cover coordination.

  Everything underneath it is the rail's problem: which fund pays, which tariff applies to that fund,
  whose balance is read, how a dependant's cover relates to a contributor's, what a household limit
  has already consumed, and how the claim is assessed against the cover it carries. You do not
  reconcile payers, rank schemes or compute what is left. You surface a choice and you report it.

### What gets stored, and why it is scoped to a contributor

The chosen cover is persisted as a snapshot alongside the authorisation, and it carries the
contributor as well as the scheme.

<ApiRef method="GET" path="/api/v1/authorizations/{token}/effective-coverage" to="/rail-api/02-verify-cover" keep="scheme_code + principal_cr_no"
  run="/api/v1/authorizations/AUTH-TOKEN/effective-coverage">
  The cover this encounter is currently billing against, with the contributor behind it and any secondary coverages. You can change it until the request is submitted.
</ApiRef>

  Both effective-coverage calls — reading it and setting it — answer 404 on the development
  gateway today. What the snapshot means has not changed, and `covers/select` is what freezes the
  choice; treat the pair below as the shape to expect rather than a call to wire in now.

`principal_cr_no` is the field that does the work here, for three reasons.

<Wire
  rows={[
    { call: "Balances are read per contributor", does: "A member's balance data holds one entry per policy, keyed by the contributor behind it. The chosen contributor selects which entry is read.", keep: "principal_cr_no" },
    { call: "Reserved amounts are scoped the same way", does: "Approved preauthorisation amounts are subtracted per contributor, so a sibling's reservation under the same encounter does not eat this contributor's limit.", keep: "principal_cr_no" },
    { call: "Getting it wrong is silent", does: "Without the contributor, the first policy would be read, quietly returning a different person's balance. That is why an unmatched contributor is an error rather than a fallback when several policies exist.", keep: "—" },
  ]}
/>

One encounter holds more than one cover through `primary_coverage` and `secondary_coverages`. The
cover frozen at visit start is the primary, and a cover chosen for a particular item links to it as a
secondary. The structure exists so that "who paid for what" is answerable per item rather than per
visit.

  Do not model the cover as a single value on the visit. Model it as a default on the visit and an
  override per item, then show the fund on each line. A provider who bills two contributors in one
  encounter and cannot see which line went where will not be able to answer a query about either.

### The two views, side by side

<Mermaid chart={`sequenceDiagram
    autonumber
    actor D as Front desk
    participant H as Your HMIS
    participant R as The rail
    actor C as Clinical / billing user

    H->>R: Valid covers for this member here
    R-->>H: Covers, public and private, each with its contributor
    D->>H: Selects one at visit start
    H->>R: Freeze it as effective coverage (primary)
    R-->>H: Snapshot stored on the authorisation
    Note over H,R: Benefits, balances and tariffs now resolve<br/>against the snapshot, not live coverage.
    C->>H: Bills an item
    H->>R: Balance for this procedure, for this contributor
    R-->>H: What that contributor has left
    C->>H: Chooses a different cover for this item
    H->>R: Link it as a secondary coverage
    R-->>H: Item carries its own scheme and fund
`} />

<Mermaid chart={`flowchart TD
    A["Valid covers returned"] --> B{How many are usable?}
    B -- One --> C["Select it, and it becomes the primary<br/>effective coverage"]
    B -- "More than one" --> D["Group by payer, rank funds inside<br/>each, operator chooses"]
    D --> C
    C --> E["Benefits, balances and tariffs resolve<br/>against the snapshot"]
    E --> F{Does this item belong to<br/>a different contributor's cover?}
    F -- No --> G["Bill against the primary"]
    F -- Yes --> H["Select that cover for the item<br/>linked as a secondary coverage"]
    H --> I["Balance and reserved amounts read<br/>for THAT contributor"]
    G --> J["Item carries its scheme and fund"]
    I --> J
`} />

## When the cover choice becomes final

The most useful thing to know about cover selection is that it sets a default rather than a
commitment. Right up until you submit, it can be changed.

<BuildSequence
  steps={[
    {
      do: "At visit start, a default is set",
      detail:
        "The cover chosen when the encounter opens becomes the primary. Everything billed under the visit inherits it unless told otherwise.",
    },
    {
      do: "At billing, changeable per item",
      detail:
        "An item can be raised against a different valid cover, typically one where the patient is a dependant of another contributor. The item carries the fund it was raised under.",
    },
    {
      do: "Before submission, still changeable",
      detail:
        "A preauthorisation or a claim that has not been submitted can have its cover changed. Amounts re-resolve against the new fund, because tariffs and limits belong to the cover rather than to the procedure.",
    },
    {
      do: "On submission, fixed",
      detail:
        "Once submitted, the cover on that preauthorisation or claim is what it will be assessed against. Changing it afterwards means a new request, not an edit.",
    },
  ]}
/>

  Providers assume the first screen commits them, so they either stall the encounter while somebody
  works out the "right" cover, or they proceed and treat a wrong choice as an unrecoverable error.
  Neither is necessary. Open the visit on any valid cover, treat care as the priority, and settle the
  cover question before the request goes out.

Two things follow for the software.

Make the cover visible and editable on the request, not only on the visit. If the only place a
cover can be chosen is the screen that opens the encounter, every correction becomes a cancellation.
Put it on the preauthorisation and the claim, with the fund shown per item.

Re-price on change, and say so. Because a procedure carries a tariff per fund, switching cover can
change the amount. Recompute rather than carrying the old figure forward, and show the operator that
the number moved, since a silently changed amount is worse than a visibly changed one.

<Mermaid chart={`flowchart LR
    A["Visit opens<br/><i>cover set as default</i>"] --> B["Items billed<br/><i>per-item override allowed</i>"]
    B --> C["Preauth / claim drafted<br/><i>still changeable</i>"]
    C --> D{Submitted?}
    D -- "Not yet" --> C
    D -- Yes --> E["Fixed, and assessed against<br/>the cover on the request"]
`} />

## Once a cover is chosen

Everything above answers *which cover pays*. The second half of the question, what that cover pays
for, is a tree you walk, and it is long enough to have its own page.

  Benefits, categories and procedures, one level at a time. How the tree is shaped, why the same rule
  lives at different depths for different payers, what a procedure declares, and where balances come
  from, with the screens, the sequence and the calls to go with them.

## The call

Two calls answer the cover question, and they run in order: coverage first, then what that cover
makes available here. The calls that walk the benefit tree are on
[the next page](/rail/guides/Benefit-Tree).

<Wire
  rows={[
    { call: "GET · eligibility", does: "Member, cover and the flags later stops depend on. Answers whether this member is current before anything else is asked.", keep: "member identifier" },
    { call: "GET · coverage", does: "Every scheme the member is covered under, one entry per contributor. This is the response that returns several rows for one person.", keep: "schemes[], policy numbers" },
  ]}
/>

Open [**02 · Verify cover in the Rail API reference**](/rail-api/02-verify-cover) to
read or run them, with a **Try it** console for when the sandbox is live.

  The field names quoted below come from one payer's current responses, included so they are
  recognisable when you meet them. Other payers use their own names for the same things, and the rail
  is normalising them, so treat the names as illustrative and the shapes as real. Exact names come
  from the reference once the contracts are signed off.

### What an eligibility response carries

Every payer answers this call with the same three things, whatever they call them: who the member
is, which cover the answer was resolved against, and a set of flags that later stops depend on.
The reference has it field by field. What follows is what to do with the flags, because those are
the ones that catch people out.

<ApiRef method="GET" path="/api/v1/beneficiaries/{unique_patient_id}/eligibility" to="/rail-api/02-verify-cover" keep="member identifier">
  Member, contacts, cover and the flags later stops depend on, including the biometric and one-time-code flags that decide what Consent can offer.
</ApiRef>

  The `/api/v1/beneficiaries/…` calls on this page — eligibility, coverage, and the retired
  `covers/valid` — answer 404. The prefix is registered nowhere in the service, so nothing behind the
  gateway serves them. What is live is
  [`GET /api/v2/patients/{unique_patient_id}/covers`](/rail-api/02-verify-cover), which returns the
  covers, their schemes, `status` and `selectable`, and a `next_action`.

  It does not carry the biometric and one-time-code flags described below, and nothing else does
  either. That is by design rather than by omission: in v2 the factors on offer are decided
  server-side per consent request and surfaced by the launch, not fetched by the integrator. Read
  what follows as the shape of a payer's eligibility answer, and let
  [03 · Consent](/rail/stops/Consent) decide the factor.

Some fields here are not about cover at all, and they matter later.
`isBiometricsEnabled`, `isFingerprintEnrolled`, `otpOnlyAllowed` and `biometricStatus` decide
which consent factors are even offered at [03 · Consent](/rail/stops/Consent). A member who is
not enrolled for fingerprints cannot consent by fingerprint, and finding that out at Consent
looks like a broken scanner.

`benefits: []` is worth reading too. An empty array here does not mean "no benefits". It means
this response did not carry them, and you fetch them per cover in the calls below.

### Coverage: one answer per scheme, per contributor

This is the response that produces several rows for one person, and it behaves the same way whoever
the payer is. A national fund returns one entry per scheme per contributor; a private insurer returns
one per policy, and a member holding both gets both sets. Nothing deduplicates them for you, and
nothing ranks them.

<ApiRef method="GET" path="/api/v1/beneficiaries/{unique_patient_id}/coverage" to="/rail-api/02-verify-cover" keep="schemes[].policy.number">
  Every scheme the member is covered under, one entry per contributor. This is the response that legitimately returns five rows for one person.
</ApiRef>

Four things to read correctly, on any payer's version of it:

<Wire
  rows={[
    { call: "The list is not deduplicated", does: "Two entries naming the same scheme are two different covers when the contributor differs. Group by contributor when you render, and use the policy number as the row identity.", keep: "policy number" },
    { call: "Status is a code, not a word", does: "Payers signal covered with a code and a human-readable message beside it. Switch on the code; show the message. Never pattern-match the text.", keep: "status" },
    { call: "Two date ranges, not one", does: "The policy window and the coverage window are different things and can differ. Coverage is the one that decides whether today is paid for.", keep: "the coverage window" },
    { call: "An empty relationship is meaningful", does: "Where the member is the contributor, the relationship field is legitimately blank. Render it as \"self\", not as missing data.", keep: "member type" },
  ]}
/>

## Public-officer and teachers' covers are a different rule set

They look like another scheme in the list. They are closer to a parallel rule set, and four
differences matter enough that treating them as a variation produces claims that cannot be paid.

<Wire
  rows={[
    { call: "Benefits downgrade, they do not vanish", does: "Where a facility has no active contract of that type, public-officer benefits are hidden and the universal or standard equivalent is shown instead. An empty list is the wrong reading; a substituted list is the right one.", keep: "which set you are looking at" },
    { call: "Teachers' members are panel-restricted", does: "Outside their panel, they see only their standard benefits. The same member gets different answers at two facilities, correctly.", keep: "—" },
    { call: "Tariffs come from a different matrix", does: "Public-officer tariffs are different figures, published separately. If the member is a public-officer member, the standard tariffs do not apply, and reading the standard matrix misprices every one of those claims.", keep: "the public-officer tariff" },
    { call: "Combination rules differ", does: "The same procedure codes, different rules about what may be billed together.", keep: "—" },
  ]}
/>

  A procedure carries both sets of figures. The cover being billed decides which one applies, so the
  same code, at the same facility, on the same day, prices differently for two patients. That is the
  rule rather than an inconsistency to reconcile.

## What you keep

<Wire
  rows={[
    { call: "The selected cover", does: "Which scheme and which contributor. Tariff, limits, documents and combination rules all follow from it.", keep: "policy number + memberType" },
    { call: "The principal contributor", does: "On a beneficiary row, whose cover is being used. The first question any audit asks.", keep: "crNumber, relationship" },
    { call: "The procedure code", does: "The unit everything later prices against, with its access point and payment mechanism.", keep: "code, access_point" },
    { call: "The effective coverage", does: "The snapshot of the chosen cover, including the contributor behind it. Everything prices against this rather than against live coverage.", keep: "scheme_code + principal_cr_no" },
    { call: "The selection reference", does: "The handle the benefit tree is read against, returned by covers/select. Short-lived and visit-scoped by design: re-run rather than caching it across days. There is no separate eligibility reference in v2.", keep: "selection_ref" },
    { call: "Consent hints", does: "Biometric enrolment and OTP flags, read here and needed at the next stop.", keep: "isFingerprintEnrolled, otpOnlyAllowed" },  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Cover selection",
      symptom: "\"There are nine identical covers, which one do I pick?\"",
      cause:
        "The contributor is not rendered. Each row is a scheme-and-contributor pair; without the contributor they look like duplicates and the operator picks the first.",
    },
    {
      where: "Cover selection",
      symptom: "\"We picked a cover and the claim was rejected as not the member's\"",
      cause:
        "A BENEFICIARY row was treated as the member's own. The claim has to carry the principal contributor for that cover, not the patient.",
    },
    {
      where: "Cover selection",
      symptom: "\"The system says not covered, so we sent them away\"",
      cause:
        "coverage.reason and message were dropped instead of shown. Identity resolved; only the money failed, and the remedy was in the response.",
    },
    {
      where: "Bill",
      symptom: "\"The line was refused and the code looks correct\"",
      cause:
        "Access point mismatch. An inpatient-only procedure was selected during an outpatient visit, and nothing failed at selection time.",
    },
    {
      where: "Bill",
      symptom: "\"It said covered, but the amount came back zero\"",
      cause:
        "A null allocated amount rendered as zero, or a household limit already spent by a relative. Read limit_applies_to before quoting a figure.",
    },
    {
      where: "Preauth",
      symptom: "\"Nobody told us this needed approving\"",
      cause:
        "needs_preauth was on the procedure and was not read. The flag is available at selection, hours before the patient is on a table.",
    },
    {
      where: "Consent",
      symptom: "\"The fingerprint reader is not working\"",
      cause:
        "The member is not enrolled for fingerprints. isFingerprintEnrolled said so at this stop.",
    },
    {
      where: "Balance screen",
      symptom: "\"The balance shown belongs to the wrong parent\"",
      cause:
        "The contributor was not sent with the balance request. Where a member has policies under several contributors, the first one is not a safe default, because it is a different person's limit.",
    },
    {
      where: "Claim query",
      symptom: "\"We cannot say which cover paid for which item\"",
      cause:
        "The cover was modelled as one value on the visit. It is a default on the visit and an override per item, and each item carries the scheme it was raised under.",
    },
    {
      where: "Bill",
      symptom: "\"The price changed when we switched cover\"",
      cause:
        "Correct. A procedure holds a tariff per fund, so the amount is a function of procedure, facility level and the cover being billed.",
    },
    {
      where: "Balance screen",
      symptom: "\"It shows zero left on emergency care\"",
      cause:
        "That benefit is not balance-tracked. There is no pool, so there is no figure, and rendering it as 0.00 tells a clinician the opposite of the truth.",
    },
    {
      where: "Balance screen",
      symptom: "\"The limit says 2 and the amount is blank\"",
      cause:
        "A count-based limit. Most limits here are numbers of visits or sessions rather than money, and a screen that only formats currency shows nothing useful.",
    },
    {
      where: "Cover selection",
      symptom: "\"We used the mother's cover and it was refused for the child\"",
      cause:
        "Benefits are filtered by member type, and a dependant may be covered under two principals. Whichever cover the request carries at submission is the one it is assessed against, so correct it before submitting rather than after.",
    },
    {
      where: "Preauth or Bill",
      symptom: "\"The document list on the procedure looked short\"",
      cause:
        "Requirements inherit from the benefit above it. Reading the leaf without resolving the chain misses everything set higher up.",
    },
    {
      where: "Next day",
      symptom: "\"The eligibility reference stopped working\"",
      cause:
        "It is visit-scoped and short-lived. Re-run eligibility rather than persisting the reference.",    },
  ]}
/>

One pattern runs through most of that list. The response said so and the screen did not. The
contributor, the access point, the limit scope, the preauth flag and the biometric flags are all
present at this stop, and every one of them, dropped here, becomes somebody else's problem later.

### Errors

<ErrorDictionary stop="entitle" />
## What carries forward

<Wire
  rows={[
    { call: "Selected cover + contributor", does: "Taken by Consent, Visit, Preauth, Bill and the claim. The single most consequential choice on this page.", keep: "Store on the encounter" },
    { call: "Procedure code", does: "Priced at Bill, approved at Preauth where required.", keep: "With its access point" },
    { call: "Consent hints", does: "They feed the factor decision at 03 · Consent. You do not make that decision, but these are among its inputs.", keep: "Pass forward, do not re-derive" },
  ]}
/>

**Next:** [03 · Consent](/rail/stops/Consent). With a cover chosen, the member has to confirm
they are present and willing.

<AgentPrompt title="Build eligibility and cover selection with an agent" filename="eligibility-and-cover.instructions.md">{`You are integrating an HMIS with the Savannah unified payer rail.

Task: implement stop 02, eligibility and cover selection. An identified patient becomes a
claim someone will pay.

ORDER MATTERS
  Coverage first (is the member paid up?), then benefits (what does the cover make
  available here?). Do not call them in parallel and do not read benefits before
  coverage has answered.

STEP 1: LIST COVERS
  Fetch eligibility for the patient at this facility.
  The response carries schemes[] with ONE ENTRY PER SCHEME PER CONTRIBUTOR. It is not
  deduplicated. The same person legitimately appears many times:
    memberType: PRIMARY      -> the member contributes to this cover
    memberType: BENEFICIARY  -> the member is covered through principalContributor
  A member may hold several schemes from one payer, and covers from several payers.
  Render every row with its principalContributor name and relationship. Without it the
  list looks like duplicates and operators pick the first row.
  Group rows by contributor. Use policy.number as the row identity, not schemeName.

STEP 2: SELECT ONE, VISIBLY
  An operator selects. Never auto-select silently: this is a financial decision and it
  must be auditable.
  There is NO precedence order between covers. Choosing a cover scopes the benefit tree to
  what that cover supports; covers often overlap, so nothing needs sorting. Do not
  pre-select across payers and do not imply a ranking.
  A dependant may be covered under MORE THAN ONE principal at once. Only one is used, it
  becomes the default for the visit, and it determines tariff, limits, documents and
  combination rules. It can be overridden per item and changed until the request is
  submitted; after submission it is fixed.
  Benefits are filtered by member type (principal / spouse / child) and by age. Never
  reuse one member's benefit list for a relative.
  Persist the selected policy number, the scheme, memberType, and the principal
  contributor's crNumber and relationship.

STEP 3: WALK TO A BILLABLE PROCEDURE, ONE LEVEL AT A TIME
  There is no call that returns the whole tree; a national scheme's procedure list alone is thousands
  of codes. ONE route returns every level, and the depth is a query filter:
    GET /api/v2/patients/{unique_patient_id}/eligibility/{selection_ref}/benefits
    no parent_code -> the top level; parent_code=<the code you chose> -> its children
    also takes: search (crosses levels), access_point, page, page_size
  selection_ref comes from POST /api/v2/patients/{unique_patient_id}/covers/select. There is no
  eligibility_ref in v2, and reading the tree takes no consent proof — the proof is redeemed at
  POST /api/v2/claims/authorize.
  Do not assume a fixed depth. Follow what comes back, and offer "select" on any node
  with no children.
  Responses may answer below the top level. Read parent codes on every node and rebuild
  the chain rather than trusting position.
  Pair drill-down with a cross-level search that returns leaves and shows the path above
  each hit: a clinician searching "dialysis" does not know which benefit it sits under.
  ATTRIBUTES CAN BE DECLARED AT ANY LEVEL. A private insurer may set preauthorisation at
  the BENEFIT level ("inpatient benefit -> preauth required"); the national scheme sets it
  at PROCEDURE level and below, varying between neighbours in one category. The same is
  true of access point, document requirements and combination rules.
  So carry a resolved context down the walk: at each level merge what that level declares
  over what you inherited, take the most specific value, and keep which node declared it
  so you can explain a refusal.
  Balances are NOT a level, and there is no selection-scoped balance route today: the
  per-procedure balance under an eligibility reference answers 404. The nearest live call is
  GET /api/v1/patients/benefits/utilization (patient_id + intervention_code), which is not
  scoped to the selected cover.
  Read four attributes before selecting a procedure:
    code, access_point (OP/IP), needs_preauth, payment_mechanism
  Filter sub-benefits and procedures by the access point of the CURRENT visit. An
  inpatient-only procedure chosen in an outpatient visit is refused at Bill, not here.
  If needs_preauth is true, route to 06 · Preauthorize before anything is done.

STEP 4: CHECK THE BALANCE WHERE THERE IS ONE
  Read utilisation where you can get it. This is informational, NOT a gate: an absent
  balance must not block selection, the visit or the claim. Treat "no route to ask" the same
  way you treat "not balance-tracked" — as unknown, never as zero.
  NOT EVERY BENEFIT IS BALANCE-TRACKED. Ambulance and emergency, outpatient primary care,
  critical care and eye health have no pool. Render a fourth state, "not tracked",
  alongside available, nearly exhausted and exhausted. Never show 0.00 for an untracked
  benefit.
  Limits are as often COUNTS as money: visits or sessions per week or year. Detect which
  kind you hold before formatting; a currency-only renderer shows nothing for most
  benefits.
  limit_applies_to may be HOUSEHOLD rather than the member: a relative's spending can
  exhaust it.
  allocated and available may be null on per-diem procedures. NULL IS NOT ZERO. Render
  "not applicable"; never display null as KES 0.00.
  Show next_available_on when a limit is spent.

COVERAGE STATUS
  Switch on coverage.status codes, not on message text.
  When nothing is active, surface coverage.reason AND coverage.message together, and keep
  the encounter open: the identity resolved, so cash or another cover is still possible.

EFFECTIVE COVERAGE: THE PART MOST INTEGRATIONS MISS
  The cover chosen at visit start is FROZEN as a snapshot (the effective coverage) and
  stored against the authorisation. Benefits, balances, tariffs, preauthorisation and the
  claim all resolve against that snapshot, not against live coverage.
  The snapshot carries the CONTRIBUTOR (principal_cr_no), not just the scheme. Send it with
  every balance request: a member with policies under several contributors has one balance
  entry per contributor, and defaulting to the first reads a different person's limit.
  Approved preauthorisation amounts are also scoped per contributor, so a sibling's
  reservation in the same encounter must not reduce this contributor's remaining limit.
  At billing, an item may be raised against a DIFFERENT valid cover, typically one where
  the patient is a dependant of another contributor. Model the cover as a default on the
  visit plus an override per item, link the override as a secondary coverage, and show the
  fund on every line.
  THE CHOICE IS NOT FINAL UNTIL SUBMISSION. A drafted preauthorisation or claim can have
  its cover changed; expose that on the request itself, not only on the visit screen, so a
  correction is not a cancellation. Once submitted it is fixed, and a change then means a
  new request.
  Re-price when the cover changes, and show the operator that the amount moved. Tariffs
  belong to the cover, not to the procedure.
  A procedure carries a tariff per fund plus fallback tariffs. Price is a function of
  procedure + facility level + the cover being billed. Re-price when the cover changes.

CARRY FORWARD
  An inactive public-officer cover with a reason is a correct answer: empanelment is per
  facility, so a cover the member holds may not pay at your site and its benefits will be
  absent from the list. Show the reason; do not render an unexplained empty list.

  Selected cover + principal contributor, procedure code + access point, and the
  consent hints read here: isBiometricsEnabled, isFingerprintEnrolled, otpOnlyAllowed,
  biometricStatus. Those decide which factors Consent can offer.
  Treat the eligibility reference as visit-scoped and short-lived; re-run rather than
  caching it across days.`}</AgentPrompt>

---

## /rail/stops/Identify

# 01 · Identify

  This is the step where you work out who is in front of you, using whatever documentation they
  carry. The patient first, then whoever treats them. Each becomes an identity the whole health
  system agrees on.

## What this step is

Someone arrives holding a national ID, a birth certificate, a refugee ID or a membership
number. Whatever it is, this step turns it into the one identifier the health system knows
them by.

Someone tells you who they are, and this step checks that against a national registry and
gives back one official answer. Patients are checked against the client registry, clinicians
against the health worker registry. It is the same question each time, asked of whichever
register is authoritative for it.

The patient's identity is the one everything after this step keys off. The clinician's is what
makes the claim defensible once care has been given.

The rule that makes it work is that an identifier without its type is not an identifier. It
is only a number, and a number resolves to nothing.

Three identities get resolved here: the patient, the clinician treating them, and the facility
they are in. The patient is the one that starts everything, so the rest of this section is
about them. The other two follow further down.

### The four moves of a lookup

The way you resolve a patient is the patient lookup, and it takes four moves:

<BuildSequence
  steps={[
    {
      do: "Pick the document type",
      detail: (
        <>
          The operator chooses what they are holding: National ID, birth certificate, refugee
          ID. That list is{" "}
          <a href="/rail/reference/Value-Sets?system=IDENTIFIER-TYPES">
            fetched from the terminology service
          </a>
          , rather than a constant in your code.
        </>
      ),
    },
    {
      do: "Send the pair",
      detail:
        "The identifier's value and its type travel together, in one call, inside your facility context.",
    },
    {
      do: "Read back one identity",
      detail:
        "The registry resolves the pair to a single record and returns the identifier the health system knows this person by, with minimal masked details so the operator can confirm the right human.",
    },
    {
      do: "Store it and carry it",
      detail:
        "Save that identifier against your own patient record. Use it for every later call in this encounter, and for every future visit by the same person.",
    },
  ]}
/>

Remember this much: <u>an identifier travels with its type, and what comes back is stored
once and reused forever.</u>

### What it looks like at the desk

Three ways to look at the same step: the screen an operator sees, the branches they can land
in, and which system answers whom.

<Wireframe
  title="Find patient"
  actor="Front desk"
  rows={[
    [
      { label: "Document type", kind: "field", span: 2, from: "IDENTIFIER-TYPES", note: "National ID · Alien ID · Refugee ID · Birth certificate · Birth notification · Mandate number · Temporary registration · Passport" },
      { label: "Number on the document", kind: "field", span: 1, note: "Scanned or typed" },
      { label: "Find", kind: "action", span: 1 },
    ],
  ]}
  caption={<>Always two inputs. A single free-text box is the commonest cause of a "patient not found" for a patient who is very much in the registry.</>}
/>

Filled in, with the values a real desk would see:

<Wireframe
  title="Find patient · 1 match"
  actor="Front desk · Example Medical Centre (FAC-2029)"
  rows={[
    [
      { label: "National ID", kind: "field", span: 2, from: "type = NATIONAL_ID", note: "Chosen from the picker" },
      { label: "33121466", kind: "field", span: 1, from: "value", note: "As printed on the card" },
      { label: "Find", kind: "action", span: 1 },
    ],
    [
      { label: "Found 1 patient with National ID 33121466", kind: "text", span: 4, note: "One match is the good case. None means re-check the type; several means ask for a second document." },
    ],
    [
      { label: "Wanjiru M****i M****i", kind: "text", span: 1, from: "name", note: "First name in full and the rest masked, enough to recognise but not enough to copy" },
      { label: "National ID · 3312****", kind: "text", span: 1, from: "matched_on", note: "Masked, and always shown with its type" },      { label: "Joined Oct 9, 2024", kind: "text", span: 1, from: "registered_on" },
      { label: "Alive", kind: "field", tone: "positive", span: 1, from: "is_alive", note: "The only status this step reports. Cover is asked at the next stop." },
    ],
    [
      { label: "SIL-UPI-0091774", kind: "text", span: 3, from: "unique_patient_id", note: "The one value to store. Every later call takes it as input." },
      { label: "View", kind: "action", span: 1, note: "Continue to cover selection" },
    ],
  ]}
  caption={<>The identifier you type is not the one you keep. You type a National ID and you store what the registry returns.</>}
/>

<Mermaid chart={`sequenceDiagram
    autonumber
    actor D as Front desk
    participant H as Your HMIS
    participant R as The rail
    participant C as Client registry

    D->>H: Picks document type, enters number
    H->>R: Lookup (type + value + facility context)
    R->>C: Resolve the identifier pair
    C-->>R: One record, or none, or several
    R-->>H: unique_patient_id, masked details, next_action
    H-->>D: Confirm the human, then continue
    Note over H,R: Store unique_patient_id now.<br/>A returning patient is never re-resolved.
`} />

<Mermaid chart={`flowchart TD
    A["Operator submits type + value"] --> B{Registry answered?}
    B -- "No, timed out" --> T["Pending, retry once,<br/>then let the desk continue"]
    B -- Yes --> C{How many records matched?}
    C -- None --> N["Not found<br/>Re-check the TYPE first"]
    C -- "More than one" --> X["Conflict<br/>Ask for a second document"]
    C -- Exactly one --> D{Is the person alive?}
    D -- No --> E["Stop. Escalate clinically."]
    D -- Yes --> F["Identity resolved<br/>store unique_patient_id"]
    F --> G["Carry it to 02 · Eligibility,<br/>where cover is asked"]
`} />

The request is the pair and nothing else. Facility travels in headers, on every call.

<Operation
  method="POST"
  path="/api/v2/patients/lookup"
  summary="Resolve an identifier pair to one unique_patient_id."
  params={[
    { name: "X-Facility-Id", type: "header", required: true, description: "The facility this call is made from." },
    { name: "X-Facility-Id-Type", type: "header", required: true, description: "How to read it: mfl, license-number, fr-code, registration-number or fid." },
    { name: "identifier.type", type: "string", required: true, description: "A code from the identifier-types value set." },
    { name: "identifier.value", type: "string", required: true, description: "As printed on the document." },
    { name: "lookup_ref", type: "string", required: false, description: "Echo a previous one to make a retry idempotent rather than a second lookup." },
  ]}
  request={`{
  "identifier": { "type": "NATIONAL_ID", "value": "33121466" }
}`}
  response={`{
  "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"
  }
}`}
/>

There is no consent block. Proving the member agreed is [3 · Consent](/rail/stops/Consent).
This call resolves an identity; it does not read a record.

#### What is redacted, and what is not

`identifiers[]` is the array the operator actually decides on. Each value shows enough to
recognise and not enough to reconstruct. The reveal is bounded so that at least the last four
characters of any identifier stay hidden, which stops the response becoming a guessing oracle.
Internal identifiers are absent rather than masked, because a masked internal id still tells a
caller the record exists in a system they have no business knowing about.

| Value | What comes back |
|---|---|
| Name | First name in full, later names keep first and last letter: `Wanjiru Mwangi Muturi` → `Wanjiru M****i M****i` |
| National ID | First 4: `33121466` → `3312****` |
| Phone | `+254700123848` → `+254700****848` |
| Email | Local part masked, domain kept: `roy.thande@example.co.ke` → `roy***@example.co.ke` |
| Registry / scheme identifiers | At most 4 leading characters: `CR6154087394882-8` → `CR61*************` |
| `unique_patient_id` | Raw. The one value you store is the one value not hidden |
| `date_of_birth` | Raw. Masking it left too little to recognise a person by |

Two habits follow. Do not mask again on top of this, or you will hide the very characters an
operator confirms against. And do not assume masking preserves length: name masking does,
phone masking does not.

#### Try it

<Postman collection="rail-01-identify.postman_collection.json" label="01 · Identify" />

Or run it directly. Set a token with Set API Token in the header, then open
[`patient.lookup` in the reference](/rail-api#tag/01--identify/post/api/v2/patients/lookup)
for the parameters, both failure bodies, and a Try it console for when the sandbox is live.

```bash
curl -sS -X POST "$RAIL_BASE_URL/api/v2/patients/lookup" \
  -H "Authorization: Bearer $RAIL_TOKEN" \
  -H "X-Facility-Id: FAC-2029" \
  -H "X-Facility-Id-Type: fr-code" \
  -H "Content-Type: application/json" \
  -d '{ "identifier": { "type": "NATIONAL_ID", "value": "33121466" } }'
```

#### The two answers that are not a 200

A `404` means re-check the type before re-typing the number. A `409` is a prompt rather than a
failure, and it carries what the desk needs to act:

```json
{
  "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"]
  }
}
```

A candidate carries no `unique_patient_id`. Until the operator has disambiguated, handing it
over would let a caller resolve a person by guessing, which is the whole reason the answer is
withheld. `disambiguate_with` names the types that would actually separate these two records,
which is more use than "collect a second identifier".

That covers one adult with one document.

  A child with no document of their own, the six situations a front desk actually meets, and what to
  do when the registry will not answer.

## Three identities, not one

A claim is never an assertion about one person. Every claim eventually has to say: *this
person, treated by that clinician, at this facility.* That is three identities and three
national registries, and they all resolve the same way, with an identifier plus what kind of
identifier it is.

What matters more than the count is the order you build them in.

<BuildSequence
  steps={[
    {
      do: "First · the patient",
      detail: (
        <>
          Resolved at the front desk, before anything clinical or financial happens. Nothing
          else can start without it: there is no cover to select, no consent to take and no
          visit to open for someone the registry has not named. Keep{" "}
          <code>unique_patient_id</code>.
        </>
      ),
    },
    {
      do: "Then · the clinician",
      detail: (
        <>
          Resolved when someone is chosen to deliver care, later in the encounter, and
          possibly more than once as staff change. It does not block the patient being
          identified, but it does block a defensible claim. Keep the{" "}
          <code>registration number</code> and the regulator that issued it.
        </>
      ),
    },
    {
      do: "Always · the facility",
      detail: (
        <>
          You never resolve this one. Your credential already carries it, and every call
          above is made inside it. Keep <code>facility_code</code> set once in your HTTP
          client rather than at each call site.
        </>
      ),
    },
  ]}
/>

Build them in that order. Nothing works without the patient. The clinician is what turns care
already given into a claim that survives review. The facility is configuration rather than
workflow.

Most integrations stop after the first, because the first is what unblocks a demo. The cost
shows up weeks later, in a rejection that names a practitioner instead of a patient.

  A patient is a number plus its document type, a clinician a number plus its regulator, a
  facility a code plus the registry it came from. Learn the pairing rule once and the other two
  cost you a form each. That is why this page teaches the patient in full and then moves fast.

Part A is the lookup you have just read. Parts B and C follow.

## Why this step exists

Everything downstream keys off one value, `unique_patient_id`: cover selection, eligibility,
authorisation, preauthorisation, reservation, billing and claims. This step is where that value
comes from, and it is the only place it comes from.

Lookup is kept separate from eligibility on purpose. A member holding three covers should not
wait on three balance checks before anyone has asked which cover they are using today. So this
call stays light, with enough to render a chooser and nothing that needs a balance.

Consent is not asked here. Resolving an identity is not the same as reading a record, and the
two are separated on purpose: proving the member agreed is [3 · Consent](/rail/stops/Consent),
once a cover is in view and there is something to consent *to*. What this call returns is
minimal and masked, enough to confirm you have the right human in front of you without handing
over the record.

## The call

Two calls make this step. One tells you which document types are currently accepted, the other
resolves the pair. Both live in the reference, with every parameter, every response code, and a
Try it console for when the sandbox is live.

<Wire
  rows={[
    { call: "GET · identifier types", does: "The document types a desk may choose from today. Fetch and cache it; never hard-code it.", keep: "code, version" },
    { call: "POST · lookup", does: "Resolves the identifier pair to one registry identity, inside your facility context.", keep: "unique_patient_id" },
  ]}
/>

Open [**01 · Identify in the Rail API reference**](/rail-api/01-identify) to read or run them.
The sidebar there is this same rail, 00 through 08, so the stop you are reading and the
endpoints you are calling stay in step. Connect once with the credentials widget in the header
and every call on that page becomes runnable.

The document types are not part of the rail's API at all. They are a coded list on the
terminology service, and this is the call:

<ValueSet
  system="IDENTIFIER-TYPES"
  label="Identifier types"
  what="The document types a front desk may choose from: national ID, birth certificate, refugee ID, and the rest. The list changes as types are added and withdrawn, so a hard-coded copy is correct the day you write it and quietly wrong months later."
/>

Three things the reference will not tell you, which is why this page exists.

<Wire
  rows={[
    { call: "Send the pair", does: "A value without its type resolves to nothing. The reference lists both fields; only this page says why sending one is the commonest false negative.", keep: "type + value" },
    { call: "Keep one field", does: "Every operation in the reference names the field worth persisting. Store it against your own patient record the first time you see it.", keep: "unique_patient_id" },
    { call: "Fetch, never embed", does: "The type list moves. A constant in your code is correct the day you write it and quietly wrong months later.", keep: "the cached version" },
  ]}
/>

## What you keep

<Wire
  rows={[
    {
      call: "POST /api/v2/patients/lookup",
      does: "Resolves the person to one identity, with masked details to confirm them",
      keep: "unique_patient_id",
    },
    {
      call: "GET /api/v1/terminology/concepts?code_system=IDENTIFIER-TYPES",
      does: "Tells you which identifier types are currently accepted",
      keep: "codes[].code",
    },
    {
      call: "GET /api/v1/professionals",
      does: "Resolves the attending clinician and returns a licence verdict",
      keep: "licence.status",
    },
  ]}
/>

`unique_patient_id` is the value that ties the rest together. Store it against your own patient
record the first time you see it. Everything after this step takes it as input, and re-resolving somebody you have
already resolved is the largest source of avoidable delay at a front desk.

Keep `lookup_ref` too, for the length of the interaction. It is the audit handle for this
resolution, and echoing it on a retry de-duplicates the attempt rather than recording a second
one.

## A · The patient

Covered above: an identifier pair resolves to one registry identity, and every later call hangs
off it.

One detail belongs here. The lookup also returns masked verified contacts, the phone and
email the member has actually confirmed. Those are the channels a one-time code goes to at
[3 · Consent](/rail/stops/Consent). When someone says "the code never arrived", start here. An
unverified channel is a dead end rather than a delay.

One habit is worth more than the rest: never store a name as free text where the registry gives
you an identifier. A typed name is only a label. The registry identifier is evidence, and
evidence is what you get asked for months later.

## B · The healthcare worker

Every billed line carries the clinician who performed it, their licence, and the body that regulates
them. Resolving that here makes the line defensible later, and it is the last cheap moment to
discover a lapsed licence.

The question is the same one asked of the patient, who are you and does your paperwork hold up,
and it is answered the same way: a number plus what kind of number it is. The regulator is half of
a registration number, exactly as a document type is half of a patient identifier.

It happens at a different moment, though, and usually on a different screen: the patient is resolved
at the desk, the clinician when care is assigned.

  The regulator picker, what a licence verdict looks like when it holds and when it does not, cadres
  and specialities, and the four things the health worker registry buys you, with the screens, the
  sequence and the workflow.

## C · The facility

  Facility resolution is real. The registry decides the tariff variant, whether a benefit is
  billable at your site at all, and which consent factors are offered. You do not call it to get
  started, though: your credential already carries a facility context, and every call on the
  rail is made inside it.

  The rest waits until the facility contracts settle. Two rules are safe to build on now. Never
  store a facility level. Read it each time, because levels and contracts change, and a stored
  level produces mispricing that is very hard to trace back. And expect a newly onboarded
  facility to be briefly absent, which is a transient to retry rather than a bug to report.

## Proving it is the same person

Resolving an identifier tells you a record exists. It does not tell you the person holding the
document is the person in the record. That proof happens at
[03 · Consent](/rail/stops/Consent), where you send a purpose and the rail
[decides the factor](/rail/stops/Consent#which-factors-a-facility-can-even-offer). What is
possible there is decided here, by flags this step returns, so it belongs on this page.

There are two paths, and they differ in kind rather than in degree.

<Wire
  rows={[
    { call: "Adults", does: "Verified against the national biometric database. Those prints were captured by the state, not by you, so template age and quality are outside anyone's control.", keep: "match or no match" },
    { call: "Minors, 7 to 17", does: "No national record exists, so they are enrolled at the point of care and the prints are sent to the biometric service. This is the only path where the prints originate with the provider.", keep: "enrolment outcome" },
  ]}
/>

  The adult match rate is around 70%. That number changes what you are building: a fallback
  used 3% of the time is an error screen, and a fallback used 30% of the time is a main path. Design
  the one-time-code route as a first-class flow with its own screens rather than an exception
  handler behind a failed scan.

Because minors are enrolled rather than matched, not every desk is an enrolment point. If your
integration serves paediatrics, find out whether the sites you are deploying to can enrol before
you assume the fingerprint path exists for them at all.

## What breaks here

Identity failures rarely announce themselves where the mistake was made. They surface later
disguised as something else, usually as "the patient's fault" or "the payer's fault".

**Patient identity**

<CostTable
  rows={[
    {
      where: "Lookup",
      symptom: "\"This patient is not in the system\"",
      cause:
        "The identifier was sent without its type, or with the wrong type. Genuine absence is rare; a mismatched type is not.",
    },
    {
      where: "Lookup",
      symptom: "\"It worked last month and now it does not\"",
      cause:
        "A hard-coded identifier type list. A type was withdrawn or renamed upstream, and the picker is still offering the old code.",
    },
    {
      where: "Cover selection",
      symptom: "\"They definitely have cover, but nothing shows\"",
      cause:
        "Resolved to the wrong person. The identifier matched more than one record and was silently disambiguated instead of being sent back for a second document.",
    },
    {
      where: "Cover selection",
      symptom: "\"The system says not covered, so we sent them away\"",
      cause:
        "A cover result treated as a lookup failure. The identity resolved; only the cover did not, and the reason and possible solution were dropped instead of shown.",
    },
    {
      where: "Consent",
      symptom: "\"The OTP never arrives\"",
      cause:
        "The contact on the registry is stale or unverified. The masked contacts returned at lookup are what consent will actually use, so offer only verified ones.",
    },
    {
      where: "Anywhere mid-encounter",
      symptom: "\"The same patient is on the bill twice\"",
      cause:
        "The patient was re-resolved partway through instead of the identity being carried forward, producing two identifiers for one person.",
    },
    {
      where: "Front desk queue",
      symptom: "\"Registration is slow at peak\"",
      cause:
        "Every visit triggers a fresh lookup. A returning patient should be read from your own record, because the registry identifier is stored once and reused for life.",
    },
    {
      where: "Claim",
      symptom: "\"Rejected, and we cannot see why\"",
      cause:
        "A name was stored as free text at intake instead of the registry identifier. A typed name is a label; the registry identifier is the evidence.",
    },
  ]}
/>

**Clinician identity**

<CostTable
  rows={[
    {
      where: "Consent",
      symptom: "\"The scan keeps failing for this patient\"",
      cause:
        "Adult prints are matched against the national database, and roughly three in ten do not match. This is the expected path rather than a fault, so fall back to a one-time code.",
    },
    {
      where: "Consent, paediatrics",
      symptom: "\"There is no fingerprint on file for this child\"",
      cause:
        "Minors have no national record and must be enrolled at the point of care. Not every site is an enrolment point.",
    },
    {
      where: "Clinician selection",
      symptom: "\"That registration number does not exist\"",
      cause:
        "The wrong regulator. The same digits can be valid under KMPDC and under another council, and the number is meaningless without the body that issued it.",
    },
    {
      where: "Billing",
      symptom: "\"Line rejected: practitioner not eligible\"",
      cause:
        "A lapsed or suspended licence, or the wrong speciality for the intervention. Licence status is checked live at billing, and checking it at selection turns this into a fixable conversation.",
    },
    {
      where: "Billing",
      symptom: "\"We cannot say who performed this\"",
      cause:
        "The clinician was picked from a typed internal list rather than the registry, so the line carries a name but no defensible registration.",
    },
  ]}
/>

Two patterns account for most of those rows. The first is an identifier sent without its type:
a patient number missing its document type, a registration number missing its regulator. The
second is a state that exists in the API but not on the screen: a conflict, an unusable cover, a
request nobody has sent yet. Neither is hard to fix, and both are expensive to find at a claim.

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 404 | `MEMBER_NOT_FOUND` | The identifier does not resolve to any registry record. |
| 409 | `IDENTIFIER_CONFLICT` | It matches more than one record and cannot be disambiguated, so collect a second identifier. |

A 409 is not a failure to retry. It is a prompt to ask the person at the desk for something
else.

## What carries forward

You leave this step holding three things. Each is an input somewhere later, and losing one
means coming back for it, usually at the worst moment.

<Wire
  rows={[
    { call: "unique_patient_id", does: "The patient's identity. Taken as input by cover selection, consent, the visit, preauthorisation, billing and the claim.", keep: "Store on your patient record, permanently" },
    { call: "Registration number", does: "The attending clinician, with the regulator that issued it. Every billed line carries it; preauthorisation re-checks the licence.", keep: "Store on the encounter" },
    { call: "facility_code", does: "Where this is happening. It is already in your credential, but it scopes every rule that follows, including pricing.", keep: "Set once in your HTTP client" },
  ]}
/>

The rail tells you where to go next. Every response carries `next_action`: switch on its
`type`, then use the `endpoint` it hands you instead of building one, because it already carries
the identity you just resolved.

```json
"next_action": {
  "type": "select_cover",
  "endpoint": "/api/v2/patients/SIL-UPI-0091774/covers"
}
```

Constructing that URL yourself works right up until a path changes. Reading it from the
response never breaks, and it lets the sequence be reordered without touching your code. The
full contract is at [next_action](/rail/concepts/Next-Action).

**Next:** [02 · Verify cover](/rail/stops/Entitle). With an identity resolved, the question becomes
which cover pays.

<AgentPrompt title="Build Identify with an agent" filename="identify.instructions.md">{`You are integrating an HMIS with the Savannah unified payer rail.

Task: implement step 1 of 8, Identify. Three identities are resolved here.

A · THE PATIENT
  Fetch the accepted document types first, and cache them by version:
    GET /api/v1/terminology/concepts?code_system=IDENTIFIER-TYPES&version=serving
  Then resolve the person by identifier pair (value + type):
    POST /api/v2/patients/lookup   { "identifier": { "type": ..., "value": ... } }
  Send X-Facility-Id and X-Facility-Id-Type on every call. Set them in the HTTP client.
  Do NOT send a consent block here. Identity resolution takes no consent; proving the
  member agreed is stop 03.
  Persist from the response:
    unique_patient_id   // the thread; every later step takes this as input
    lookup_ref          // echo it on a retry so the attempt is de-duplicated
    contacts            // masked; these are the channels consent will use later
  Treat unique_patient_id as opaque: store it, send it, never parse it.
  Everything masked in the response is already safe to render. Do not mask it again, or you
  will hide the characters the operator confirms against.
  On 409, read detail.candidates and detail.disambiguate_with and ask for one of those
  document types. A candidate never carries a unique_patient_id.

B · THE HEALTHCARE WORKER
  Resolve the attending clinician by regulator + registration number. The regulator is part
  of the identifier: KMPDC, Clinical Officers Council, Nursing Council of Kenya.
  Check licence status live and refuse a suspended or lapsed practitioner at selection time.
  Do not attach them and discover it at billing.
  Persist the registration number and its regulator on the encounter.
  Where an intervention needs clinical sign-off, request approval and model these states
  explicitly: not sent, pending, approved, declined. Provide a way to re-check; the answer
  arrives out of band.

C · THE FACILITY
  Do not call for this. Your credential carries the facility context; set the facility headers
  once in your HTTP client rather than at individual call sites. Never store a facility level.
  Read it, because it changes and a stored level produces mispricing.

PROVING IDENTITY (decided here, exercised at Consent)
  Adults are matched against the national biometric database; expect roughly a 70% match
  rate and treat the one-time-code fallback as a MAIN path with its own screens, not an
  error handler.
  Minors aged 7-17 have no national record: they are enrolled at the point of care, and
  not every site can enrol. Do not assume a fingerprint path exists for paediatrics.
  Carry forward the flags this step returns (biometric enrolment and OTP eligibility)
  rather than re-deriving them at Consent.

RULES
- An identifier is always a pair. Never send a bare number: a patient identifier without its
  type, or a registration number without its regulator, is the commonest false "not found".
- Never hard-code a coded list. Fetch, cache by version, filter to active for pickers.
- Never store a patient name as free text where a registry identifier exists.
- Mask names, identifiers and contacts on screen.
- Handle a conflict by prompting for a second document, not by retrying the same call.
- A resolved patient with unusable cover is not a lookup failure: surface the reason and the
  possible solution, and let the encounter proceed as cash or on another cover.
- Every response carries next_action. Switch on next_action.type and take the endpoint from
  the response rather than constructing it. Do not hard-code the sequence.`}</AgentPrompt>

---

## /rail/stops/Preauth

# 06 · Preauthorize

  Approval is per item and can be partial. Bill against what was approved, never against
  what you asked for.

## Why this stop exists

Some items may not be done until someone has agreed to pay for them. Two things put a line
here: an item flagged as requiring preauthorisation at the benefit level, or an item flagged
conditional whose condition has now been met.

Either way the affected lines are **held**: they sit visibly on the bill while everything
else proceeds normally. Approval releases them without touching the rest of the invoice.

This is an interchange. The rail forks here between carrying on with the billing and waiting
for a decision that is being made somewhere else.

## One envelope, one clinical block

Every preauthorisation carries the same outer envelope: the visit, the requesting doctor,
the primary diagnosis, the billed items. That part never changes.

What changes is the **clinical block**, and the benefit type decides which one applies. A
surgical request does not have to prove the same things as a renal, oncology, radiology or
optical one.

<Anatomy
  cards={[
    {
      title: "Envelope (always)",
      required: ["visit_id", "request_type", "narrative", "service_start", "items[]", "diagnosis", "doctor"],
      note: "request_type is planned or emergency. narrative has an enforced minimum length, because a human reads it.",
    },
    {
      title: "Surgical",
      required: ["procedure", "admission_type", "surgeon_notes"],
      optional: ["pre_op_reports", "second_opinion"],
      note: "Surgery date does not default. A major procedure may require several sign-offs before a decision is possible.",
    },
    {
      title: "Renal",
      required: ["modality", "sessions_per_week", "dry_weight"],
      optional: ["latest_creatinine"],
    },
    {
      title: "Optical",
      required: ["visit_date", "lens_type", "prescription"],
      optional: ["frame_details", "previous_specs", "last_replacement"],
    },
  ]}
/>

The division of labour is deliberate. Your system already knows what clinical data belongs
to each benefit type, and populates it. The rail then confirms, before it accepts anything,
that everything the benefit type requires *on the current payer* is present and well formed.
Where something is missing it rejects the request and names the missing field, rather than
passing a half-formed request downstream.

## Submit

<ApiRef method="POST" path="/api/v1/preauths" to="/rail-api/06-preauthorize">
  Submit a preauthorisation. The rail validates it against the requirement map for this benefit type and payer.
</ApiRef>

Submission accepts an `idempotency_key`. A retry after a network failure then returns the
original reference rather than creating a duplicate. Use it, because duplicates here are
expensive to unpick.

## The states

There is one status enum whichever payer is deciding, so your state machine never has to
branch on payer.

<Wire
  rows={[
    { call: "submitted", does: "Received, routing in progress", keep: "not terminal" },
    { call: "under_review", does: "A reviewer or rule is assessing it", keep: "not terminal" },
    { call: "awaiting_doctor_review", does: "Routed for clinical sign-off", keep: "doctors_signed_off / doctors_required" },
    { call: "awaiting_manual_approval", does: "A payer officer must approve by hand", keep: "not terminal" },
    { call: "approved", does: "Full approval", keep: "authorization_code" },
    { call: "partially_approved", does: "Some items approved, some not", keep: "per-item amounts" },
    { call: "rejected", does: "No items approved", keep: "terminal" },
    { call: "returned", does: "Sent back for correction", keep: "resubmit under the SAME reference" },
    { call: "expired", does: "The decision window elapsed", keep: "terminal" },
    { call: "withdrawn", does: "An approval already given is taken back. It is rare and terminal, and most state machines have no branch for it.", keep: "terminal, stop billing against it" },
    { call: "cancelled", does: "Withdrawn by the requester before a decision", keep: "terminal" },
    { call: "lapsed", does: "Approved, but the window to start the work passed unused", keep: "terminal, request again" },
  ]}
/>

Twelve states, and the three at the bottom are the ones integrations miss. An approval can be
withdrawn after it was given, so "approved" is not a fact you can cache and stop watching. Keep
listening on the reference until the work is billed.

  Approval and the window to use it are two different things. An elective approval that is never
  acted on lapses, and the exact window is one of the figures still being confirmed, see
  [time limits](/rail/reference/Time-Limits). Store the expiry that comes back with the approval and
  show it on the case rather than inferring it.

## The decision

<ApiRef method="GET" path="/api/v1/preauths?preauth_reference=" to="/rail-api/06-preauthorize">
  The current state, and the decision once there is one. The body is identical to the callback's.
</ApiRef>

Bill checks `valid_from` and `valid_to` again when the line is added, so the check does not
only happen here. Billing after the window closes needs a fresh preauthorisation rather than
a reuse of this decision.

  On some payers an approval creates the reservation by itself, and `next_action` points
  straight past it to billing. On others you have to request the reservation explicitly, and
  `next_action` says `reserve`. Read it rather than assuming. This is exactly the case a
  hard-coded sequence gets wrong.

## Seven request types, and they behave differently

A preauthorisation is not one shape. The type decides the required fields, the validation, and in
some cases whether a doctor has to sign it, so read the type from the procedure rather than
defaulting to a generic request.

<Wire
  rows={[
    { call: "OUTPATIENT · INPATIENT", does: "The general paths. Neither demands a type-specific clinical block, though inpatient carries injury and admission detail where relevant.", keep: "the type" },
    { call: "SURGICAL", does: "Its own clinical block, an anaesthesia type, and, where enabled, a doctor's authorisation before it can proceed. It needs a credentialed surgeon, and where an anaesthetist is required, that is a second named practitioner.", keep: "surgery date" },
    { call: "RENAL", does: "The strictest of the set: sessions required and an expected session date are both mandatory, because dialysis is authorised as a course rather than an event.", keep: "sessions_required, session date" },
    { call: "ONCOLOGY", does: "Sessions and expected date, plus comorbidity and metastases detail. Live for named facilities rather than everywhere.", keep: "sessions_required" },
    { call: "RADIOLOGY", does: "Clinical indications and, where sedation is involved, an anaesthesia type.", keep: "clinical indications" },
    { call: "OPTICAL", does: "A prescription block per eye (sphere, cylinder, axis, add) plus frame detail. Age limits apply to some optical benefits.", keep: "the prescription" },
  ]}
/>

  The set above is what the rail models. Which of them a given payer accepts is configured per payer,
  so a type that works on the national scheme may not be enabled on a private insurer. Read the flags
  on the procedure, `needs_preauth` and the speciality-specific ones for renal, oncology, radiology,
  surgical and optical, rather than inferring the type from the benefit's name.

**Sessions are the pattern worth reading.** Renal and oncology authorise *a course of treatment*
rather than a single act: you say how many sessions and when they start, and the approval covers the
series. It is the same idea as `isMultisession` on the procedure, so do not raise a fresh request
per session.

## Required fields differ per request type

Each clinical path has its own required set, and the differences are exactly where requests get
rejected. Four of them are worth stating plainly, because earlier material had them wrong:

<Wire
  rows={[
    { call: "Surgical", does: "Seven required fields, not six. The surgery date is required, though earlier material described it as optional.", keep: "surgery_date" },
    { call: "Renal", does: "Five required fields, not four. The start date is required.", keep: "start_date" },
    { call: "Oncology", does: "Five required fields, not four. There is no cancer-staging field on this path, whatever earlier material implied.", keep: "—" },
    { call: "Optical", does: "All four description fields can be filled. It is the lens prescription that cannot.", keep: "—" },
  ]}
/>

  A practitioner's regulating body is sent as **`regulation_body`**. Sending `regulator` does not
  degrade gracefully: the request is rejected. The concept is the one taught at
  [01 · Identify](/rail/stops/Identify), and only the wire name differs, so it is worth grepping your
  code for.

**Extra items are dropped quietly rather than refused.** If you send items the request type does
not accept, the preauthorisation is created without them and nothing tells you. Compare what you
sent with what comes back, item by item, rather than trusting a 201.

## Decisions arrive; they are not returned

Preauthorisation is asynchronous. There is no synchronous approval.

- Register a callback once for `preauth.decision`. It is signed, retried with backoff, and safe to receive twice.
- Poll `GET` at the interval in `poll_after_ms`. It returns the same body as the callback.

Build both. The callback is the fast path; polling is the guarantee.

  It is easy to assume both run through [03 · Consent](/rail/stops/Consent), and they do not. That
  stop authenticates **the member**: is this the person, are they present, do they permit this. A
  doctor's approval is a practitioner's clinical decision on a specific request, recorded against
  the preauthorisation with its own review status, its own doctor roles (a surgeon, and where
  required an anaesthetist), and its own channels.

  They share a shape: a request goes out, an answer arrives out of band, and neither is something
  you poll into existence. Their purpose is different, so do not try to satisfy a doctor's approval
  with a member's proof, or the reverse.

## The doctor workflow

Where an intervention needs clinical sign-off, the request has to reach a specific practitioner.
This is the most under-documented part of the step relative to how often it goes wrong.

<Wire
  rows={[
    { call: "Channels differ per facility", does: "A request can go to the doctor's app, by two-way SMS, or by email, and not every facility is enabled for all three. A request sent on a channel the facility is not enabled for never arrives at all.", keep: "the enabled channels" },
    { call: "Resend is required behaviour", does: "If the first request fails, or the doctor never saw it, you must be able to resend to any doctor on the preauthorisation.", keep: "—" },
    { call: "Remove is required too", does: "After a rejection, the doctor can be removed and another attached.", keep: "—" },
    { call: "Some interventions need several doctors", does: "More than one signature triggers peer review. Read the requirement from the intervention rather than assuming one doctor is enough.", keep: "how many are required" },
  ]}
/>

A peer review decision is recorded, displayed, and **final once made.** Build the display, because
there is no path that reverses one.

  A surgical request needs a practitioner registered and credentialed in the surgeon speciality
  rather than one who merely holds a valid licence. That is a speciality check at
  [01 · Identify](/rail/stops/Identify), done when the clinician is chosen, hours before this request
  is raised.

## Documents, and when each is checked

The required list is published per intervention, and **the check happens at different points**:
some documents at preauthorisation, some at the claim. Inpatient submissions need a discharge
summary and a final bill, while maternity needs only the discharge summary. Collecting the right
set at the wrong moment still fails.

<BuildSequence
  steps={[
    { do: "Read the list from the intervention", detail: "Not from a general list. Two interventions in the same category can require different documents." },
    { do: "Note which stage each belongs to", detail: "Preauthorisation documents and claim documents are separate sets, and the response distinguishes them." },
    { do: "Make uploads idempotent", detail: "A retried upload must not create a second attachment." },
    { do: "Send the correct content type", detail: "A PDF sent as something else produces a confusing failure rather than a clear rejection." },
  ]}
/>

  Whether attachment checking is enforced in production is not yet confirmed. If it is off today,
  an integration with missing documents will pass quietly and start failing the day it is switched
  on. Build to the published requirements rather than to what the environment currently accepts.

## Every line carries its scheme code

A preauthorisation item, like a claim line, is billed against a fund, and the **scheme code on the
line is what routes it there.** It is not an optional override. Lines on one visit can legitimately
carry different scheme codes, because a member's covers differ by benefit.

Send it on every item. A line without one, or with the wrong one, is routed to the wrong fund and
comes back as an assessment problem rather than a routing problem.

## What breaks here

<CostTable
  rows={[
    {
      where: "Preauth",
      symptom: "\"We sent three items and only one came back\"",
      cause: "Some payers accept one item per request. Send one request per item unless you have confirmed otherwise, because the quiet drop is the worst failure mode on this stop.",
    },
    {
      where: "Preauth",
      symptom: "\"It was rejected for a missing field we did send\"",
      cause: "Arrays travelling as encoded text in a form field can arrive empty rather than erroring. Verify the payload shape as well as its contents.",
    },
    {
      where: "Bill",
      symptom: "\"Approved, but billing still refuses the line\"",
      cause: "The approval window closed. valid_to is checked at the moment the line is added.",
    },
    {
      where: "Reconcile",
      symptom: "\"We billed the approved amount and were still short-paid\"",
      cause: "The header total was used instead of the per-item approved amounts. Partial approval is per line.",
    },
  ]}
/>

<CostTable
  rows={[
    {
      where: "Bill",
      symptom: "\"We billed against an approval and it was refused\"",
      cause:
        "The approval was withdrawn after being given. Approved is not terminal, so keep watching the reference until the work is billed.",
    },
    {
      where: "Preauth",
      symptom: "\"The request was rejected and the payload looks complete\"",
      cause:
        "A per-type required field is missing, such as the surgery date on a surgical request or the start date on a renal one, or regulation_body was sent as regulator.",
    },
    {
      where: "Preauth",
      symptom: "\"Half the items are not on the approval and we were not told\"",
      cause:
        "Extra items are dropped quietly rather than refused. Reconcile what you sent against what came back, item by item.",
    },
    {
      where: "Visit",
      symptom: "\"The approval expired before the patient came in\"",
      cause:
        "An elective approval has a window to be acted on. Store the expiry with the approval and surface it.",
    },
  ]}
/>

## Next

**Next:** [07 · Bill](/rail/stops/Bill)

<AgentPrompt>{`You are integrating an HMIS with the Savannah unified payer rail.

Task: implement stop 05, Preauth.

1. POST /api/v1/preauths with the common envelope (visit_id, request_type,
   narrative, service_start, items[], diagnosis, doctor) plus the clinical block
   required by the item's benefit type.
2. Send an idempotency_key so retries do not create duplicates.
3. Handle the decision asynchronously: have a delivery target for
   preauth.decision (the endpoint registered at stop 00, or an X-Callback-Url
   header on this request) AND poll GET /api/v1/preauths?preauth_reference= at
   poll_after_ms. Build both.
4. On approval, read next_action, it either points to a reservation call or
   straight to billing. Do not assume which.

Rules:
- Approval is PER ITEM and can be partial. Bill against approved_amount and
  approved_quantity per line, never the header total.
- Respect valid_from / valid_to. Billing outside the window needs a fresh preauth.
- A "returned" status is resubmitted under the SAME reference, not as a new one.
- Treat request_failed as retryable; it is not a decline.
- Send one item per request unless you have confirmed batching is supported.`}</AgentPrompt>

---

## /rail/stops/Reconcile

# 09 · Reconcile

  Approved is not paid, and a facility with no approved bank record is paid nothing.

  Both calls on this page — registering a callback and polling remittances — are unregistered in
  the service today. There is no reconciliation surface behind the gateway yet.

  Read this stop now anyway, because what it describes is the work you will have to do and the
  shape it will take, and because the mistakes below are made at design time rather than at
  integration time. Callback endpoints, meanwhile, are registered per tenant at
  `/api/v1/tenants/{tenant_id}/endpoints`, which is live — see
  [00 · Authenticate](/rail/stops/Authenticate).

## Why this stop exists

This is the stop integrations most often leave until it is urgent. An approved claim is a
decision, not a payment. The money arrives separately, in batches, on a schedule of its own,
and matching it back to what you billed takes real work.

It is also where "we have been live three weeks and no money has arrived" gets answered. The
answer is usually banking rather than claims.

## Register a callback once

<ApiRef method="POST" path="/api/v1/callbacks" to="/rail-api/09-reconcile">
  One registration covers preauth decisions, claim decisions and remittance postings.
</ApiRef>

Register it at Authenticate, before you need it. Claim submission will not proceed without a
`claim.decision` registration.

## The remittance event

```json
{
  "event": "remittance.posted",
  "remittance_id": "RMT-2026-08-0091",
  "batch_ref": "BATCH-2026-08-19",
  "posted_at": "2026-08-19T14:00:00+03:00",
  "claims": [
    {
      "claim_id": "CLM-2026-081234",
      "amount_paid": { "amount": 1200, "currency": "KES" },
      "status": "paid"
    }
  ]
}
```

Upstream, payers post remittances on their own schedules and in their own batch shapes. You
receive one event shape. Treat the batch reference as the idempotency key. A batch can be
retried, and receiving one twice must not pay you twice in your own ledger.

## Poll to close gaps

<ApiRef method="GET" path="/api/v1/remittances" to="/rail-api/09-reconcile">
  Paginated remittances since a timestamp. The body is the same as the callback, so you can reconcile with it after any webhook gap.
</ApiRef>

Webhooks tell you sooner, but they do get missed. Run a scheduled poll as well, so a missed
delivery does not become a month-end problem.

## Match on the invoice, never on the money

Getting this wrong causes more rework than anything else at this stop.

Match a remittance to the **provider invoice reference**. Do not match on member, amount or
date, because all three collide and amounts rarely equal what you billed once deductions
land. Model **many advices to one invoice**: interim payments are normal, and a single
invoice may be settled across several batches.

<Wire
  rows={[
    { call: "Discount", does: "An agreed reduction that lowers revenue", keep: "posts to revenue reduction" },
    { call: "Member copay", does: "The patient's share, collected by you", keep: "already yours" },
    { call: "Withholding tax", does: "Deducted at source", keep: "reclaimable, not lost" },
    { call: "Rejected amount", does: "Refused, with a reason", keep: "reason code" },
    { call: "Shortfall", does: "Paid less than billed, and none of the above explains it", keep: "posts to suspense" },
  ]}
/>

Discount and shortfall land in **different ledger accounts**. Treating a shortfall as a
discount quietly writes off money you could still recover.

## Why money has not arrived

Ordered by how often each one turns out to be the cause:

<BuildSequence
  steps={[
    "No approved banking record. A human reviews it, and until it is approved nothing pays out however many claims are approved. Start this on day one, alongside the build.",
    "The claim is approved but not yet in a payment batch. Approved is a decision, and batches run on their own schedule.",
    "The claim was returned rather than decided, and nobody resubmitted it. Returned is not the same as rejected. It is waiting for you.",
    "The claim was reconciled against the wrong invoice reference, so the payment did arrive and then sat unmatched in your own system.",
    "The claim timed out. There is a hard time bar from the date of service, and a claim that misses it cannot be revived.",
  ]}
/>

## What breaks here

<CostTable
  rows={[
    {
      where: "Reconcile",
      symptom: "\"We have been live for weeks and nothing has been paid\"",
      cause: "Almost always an incomplete or unapproved banking record, not a claims problem at all.",
    },
    {
      where: "Reconcile",
      symptom: "\"The payment does not match any claim\"",
      cause: "Matching was attempted on member, amount or date. Match on the provider invoice reference.",
    },
    {
      where: "Reconcile",
      symptom: "\"We were paid twice for one batch\"",
      cause: "The batch was retried and ingested twice. batch_ref is the idempotency key.",
    },
    {
      where: "Reconcile",
      symptom: "\"The totals are short and we cannot explain it\"",
      cause: "Deductions were collapsed into one figure. Reconcile the claim total and explain each gap by its own flag.",
    },
  ]}
/>

## You have reached the end of the rail

That is the full journey: your system on the rail, a patient resolved, cover chosen,
consent proved, an encounter opened and closed, a claim assembled and sent, and money
matched back to it.

Every scenario you meet from here is this sequence with different values in it.

**Back to:** [the whole line](/rail/concepts/The-Eight-Steps) · [why it exists](/rail/why/The-Problem)

---

## /rail/stops/Submit

# 08 · Submit

  Pre-flight should hold no surprises. Every check it runs has been running since you added the
  first line.

## Why this stop exists

Two things happen here, in order, and they get conflated: the visit closes, then the claim is
sent. Closing needs consent from the patient. Sending needs the claim to be complete.

## Close the visit with consent

A visit closes the way it opened, with consent. Discharge is authorised in its own right
rather than treated as a formality.

Two pre-discharge checks run before the closing consent is even offered. Every unretired line
must have an active reservation, and where the visit was opened from a card swipe, the
authorisation has to trace back to a live session rather than to some other factor.

<ApiRef method="POST" path="/api/v2/patients/{unique_patient_id}/authentications" to="/rail-api/03-consent" keep="closing_authorization_ref">
  Ask for the closing authentication. It is the same call as visit open, with purpose set to close
  the visit. See [03 · Consent](/rail/stops/Consent#what-you-send-and-what-you-get-back).
</ApiRef>

Closing is a purpose of its own. A proof taken to open the visit can never satisfy it, however
strong and however recent it is, so there is nothing to reuse here and no shortcut worth hunting
for. The reason for that rule, and what it prevents, is at
[one proof, spent more than once](/rail/stops/Consent#one-proof-spent-more-than-once).

`closing_authorization_ref` travels onto the claim.

  Neither `/api/v1/visits/{visit_id}/claim/preflight` nor `/api/v1/visits/{visit_id}/claim/close` is
  registered. The registered preflight, `POST /api/v2/visits/{visit_ref}/preauths/preflight`, checks
  a preauthorisation rather than a claim, and closing exists as `POST /api/v1/claims/close` and
  `POST /api/v1/visits/{visit_id}/close` — different calls with different bodies, not renames of
  these. Read the gates below as the rule; do not wire the paths yet.

## Pre-flight: the six gates

<Wire
  rows={[
    { call: "Reservation exists", does: "Every billed line traces to a reservation", keep: "reservation_id per line" },
    { call: "Amount ≤ reserved", does: "No line bills more than was held for it", keep: "—" },
    { call: "Lines mapped", does: "Every code has an unbroken path to a payer revenue code", keep: "mapping" },
    { call: "Attachments present", does: "Every requiredDocuments entry has a matching document", keep: "document keys" },
    { call: "Diagnosis present", does: "Exactly one primary diagnosis is recorded, each linked to the intervention it justifies. This is recorded at 05 · Treat rather than assembled here", keep: "icd11_code" },
    { call: "Dates within cover", does: "Visit dates fall inside the cover's validity window", keep: "—" },
  ]}
/>

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/claim/preflight" to="/rail-api/08-submit">
  Run every gate and return all failures at once, each with a route to its fix.
</ApiRef>

Every reason carries `fix_stage` and `fix_label`. Use them to send the operator straight to the
screen that can resolve the problem, rather than showing a list and leaving them to hunt.

Severity matters. A `blocker` stops submission and a `warning` does not, but a warning cannot
ride through unexamined either, so it persists until someone confirms it.

## Close and submit

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/claim/close" to="/rail-api/08-submit">
  Re-run every gate, then submit. Idempotent on external_id.
</ApiRef>

There is one endpoint, whichever payer the claim is destined for. The dispatch decision was made
back at eligibility when the cover was chosen and has been carried on every line since, so you
never select a different endpoint per payer.

Submission needs somewhere to deliver the decision, and that is a precondition, not a nicety. If
there is no registered `claim.decision` endpoint and no `X-Callback-Url` header on the request,
you get `CALLBACK_NOT_REGISTERED`. Register the default once at
[00 · Authenticate](/rail/stops/Authenticate) and you will never see the check. Use the header
when one particular claim's outcome belongs somewhere else.

## Six kinds of claim, and eleven states

Two counts are worth correcting, because a state machine built to the wrong one leaves cases with
no branch.

There are six claim types, not four. Ambulance is live and behaves differently from everything
else, and oncology is live for named facilities rather than still in development. Treat the type as
data on the claim and switch on it, rather than assuming one shape.

The authorisation moves through eleven states, not four. These are the states of the
*authorisation* that opened and closed the visit, a different enum from the twelve a
[preauthorisation](/rail/stops/Preauth#the-states) moves through, and the two are easy to confuse.
Anything modelled on "pending, approved, rejected, done" will meet states it quietly drops. Read
the enum from the reference, and when a value arrives that you do not know, hold the claim instead
of discarding it.

  How long you have to submit is one of the numbers our own sources disagree about, and the two
  candidates are far enough apart to imply different products: a monthly reconciliation habit, or a
  daily worklist with alerting. Read [time limits](/rail/reference/Time-Limits), keep the value in
  configuration, and show the deadline on the claim rather than enforcing it silently.

Missing documents have their own terminal deadline. A claim returned for documents can be
resubmitted, but only inside a window, after which it is rejected and cannot be resubmitted at all.
It is the one deadline where nothing can be recovered afterwards, so it belongs on a worklist of its
own rather than in a general queue.

## After it lands

Submissions are reviewed in batches with rules doing part of the work, but anything with an issue
goes to a person. Expect decision latency to reflect that.

Decisions are per line and can be partial:

```json
{
  "event": "claim.decision",
  "claim_id": "CLM-2026-081234",
  "decision": "partially_approved",
  "lines": [
    { "line_ref": "lin_007", "decision": "approved", "approved_amount": { "amount": 1200, "currency": "KES" } },
    { "line_ref": "lin_013", "decision": "rejected", "reason": "Tariff not covered at this facility level." }
  ]
}
```

A claim can also come back **returned**, meaning sent back with feedback for correction rather
than rejected. It keeps its `claim_id` and is resubmitted under the same `external_id`. A
resubmitted bill may not exceed the original.

## Documents are checked in two places

The required list is per procedure, and it splits across two moments: some documents belong to the
preauthorisation and some to the claim. An inpatient submission needs a discharge summary and a final
bill; maternity needs only the discharge summary. Collecting the right documents at the wrong stage
still fails here.

Two practical rules. Uploads must be idempotent, so a retry does not create a second attachment.
PDFs must be sent with the correct content type, because the failure you get when they are not is
confusing rather than explicit.

  We have not confirmed whether the attachment check runs in production. If it is off today, a
  submission with missing documents passes quietly and starts failing the day someone switches it
  on. Build to the published requirements rather than to what the environment accepts today.

## What breaks here

<CostTable
  rows={[
    {
      where: "Submit",
      symptom: "\"It will not let us submit and we cannot see why\"",
      cause: "Pre-flight returned blockers. Every one carries a fix_stage, so surface them as actions rather than as a wall of text.",
    },
    {
      where: "Submit",
      symptom: "\"Callback not registered\"",
      cause: "A callback for claim.decision has to exist before any claim can be sent. Register it at Authenticate rather than here.",
    },
    {
      where: "Submit",
      symptom: "\"The visit will not close\"",
      cause: "Almost always the missing discharge consent. Closing needs an authentication of its own.",
    },
    {
      where: "After",
      symptom: "\"We resubmitted and now there are two claims\"",
      cause: "A new external_id was generated. Reuse the original one, because submission is idempotent on it.",
    },
  ]}
/>

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 422 | `NOT_READY` | Close called while pre-flight is `ready: false`. |
| 409 | `CALLBACK_NOT_REGISTERED` | No callback exists for `claim.decision`. |
| 409 | `CLAIM_DATE_OUT_OF_COVER` | A billed date falls outside the cover's window. |
| 409 | `RESERVATION_MISSING` | A line has no active reservation at discharge. |

<CostTable
  rows={[
    {
      where: "Submit",
      symptom: "\"The claim sat in our queue and the window closed\"",
      cause:
        "Someone assumed the time bar was generous. It is disputed and may be short, so show the deadline on the claim and alert before it rather than after.",
    },
    {
      where: "Submit",
      symptom: "\"A returned claim can no longer be resubmitted\"",
      cause:
        "The missing-documents window elapsed. That deadline is terminal, and nothing recovers the claim afterwards.",
    },
    {
      where: "Anywhere",
      symptom: "\"Our state machine has no branch for this status\"",
      cause:
        "Eleven authorisation states and six claim types, and preauthorisations have their own twelve. Handle an unknown value by holding the claim rather than dropping it.",
    },
  ]}
/>

## Next

**Next:** [09 · Reconcile](/rail/stops/Reconcile)

---

## /rail/stops/Treat

# 05 · Treat

  A diagnosis costs one click while the clinician is still in the room. Reconstructed weeks
  later from a rejected claim, it costs somebody a morning, and what you end up with is a
  guess with a code on it.

## Why this stop exists

Between opening the encounter and billing for it, somebody is examined, something is found
and something is done. Every stop around this one already assumes that record exists.
Preauthorisation asks for the diagnosis behind the request. The claim carries one diagnosis
per intervention and is assessed on the pair. The patient's next facility needs to know what
happened at this one.

Without a stop of its own, all of that gets assembled at submission by whoever is closing
the claim. That is the wrong person at the wrong time, working from notes rather than from
the encounter.

This is an interchange, and the fork is an unusual one. One branch carries the clinical
record onward to the payer, and the other leaves the rail entirely for the shared health
record. The same act of recording feeds both, so you only do it once.

## What is recorded here

<Wire
  rows={[
    { call: "The diagnosis", does: "What was found, as an ICD-11 code taken from the terminology service. It is never typed by hand and never mapped from a local string at submission time.", keep: "diagnosis_id" },
    { call: "The link to the intervention", does: "Which billable intervention this diagnosis justifies. The payer assesses the pair, so a diagnosis with nothing attached fails, and so does an intervention with nothing behind it.", keep: "intervention_code" },
    { call: "The encounter itself", does: "The clinical facts as FHIR: observations, notes, impressions and the conditions treated. They are written to the shared health record through the same call.", keep: "bundle_id" },
    { call: "What was requested", does: "Orders and prescriptions. They are routed to whoever performs them, frequently not you, and answered back against the request.", keep: "order_id, prescription_id" },
    { call: "Where the patient goes next", does: "Referrals and specimens, carrying the record and the authorisation already taken here.", keep: "referral_id" },
  ]}
/>

The first two are what stop claims bouncing. The rest is what makes the record worth having,
because the same facts, recorded once, serve the claim, the next facility, the patient's own
record and, as the last section on this page explains, the documents the claim requires.

Recording clinically is the decision everything else rests on. The rest of this stop follows
from having done it.

## Take the code from the service, not from a list you keep

  `GET /api/v2/clinical/diagnoses` is 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, and which the
  [terminology reference](/rail/reference/Terminology-Service) documents in full.

  Recording a diagnosis is live, at `POST /api/v2/visits/{visit_ref}/diagnoses`. Reading them back
  off a visit and withdrawing one are not.

<ApiRef method="GET" path="/api/v2/clinical/diagnoses" to="/rail-api/05-treat">
  Search ICD-11 for a codable diagnosis in the release the payer is currently validating against.
</ApiRef>

Two properties of the response decide whether the claim survives.

<Wire
  rows={[
    { call: "codable", does: "ICD-11 contains groupings and chapter headings that are not diagnoses. They come back in a search and they are rejected at assessment. Offer only entries flagged codable.", keep: "codable: true" },
    { call: "version", does: "The release the payer validates against moves. A code cached from an older release can be retired without your picker noticing.", keep: "the version you resolved against" },
  ]}
/>

  They do not come from clinicians choosing badly. They come from pickers built once, from a
  spreadsheet, and never refreshed after that. The full walkthrough is at
  [fetching a coded list](/rail/reference/Value-Sets) and
  [pinning to a release](/rail/reference/Terminology-Pinning-Versions).

## Record it against the visit

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/diagnoses" to="/rail-api/05-treat">
  Record a diagnosis on the visit, linked to the intervention it justifies.
</ApiRef>

<Anatomy
  cards={[
    {
      title: "Always",
      required: ["icd11_code", "description", "rank", "intervention_code"],
      note: "rank is primary or secondary. Exactly one primary per visit, any number of secondaries.",
    },
    {
      title: "Where the clinician knows it",
      optional: ["certainty", "onset", "recorded_by"],
      note: "certainty is confirmed, provisional or differential. A provisional diagnosis is a legitimate thing to record and to bill against, not a placeholder to be tidied up later.",
    },
  ]}
/>

Build the workflow around `intervention_code`. It is not metadata on the diagnosis; it is the
assertion the payer assesses. One diagnosis can justify several interventions, and several
diagnoses can sit behind one, so record the pair each time rather than recording a list of
codes and hoping the assessor infers the pairing.

## The record is amended, never rewritten

<ApiRef method="DELETE" path="/api/v1/visits/{visit_id}/diagnoses/{diagnosis_id}" to="/rail-api/05-treat">
  Withdraw a diagnosis recorded in error, while the visit is still open.
</ApiRef>

Withdrawal is available until the claim is submitted, and refused after it with
`DIAGNOSIS_LOCKED`. That is deliberate, because once a claim has been assessed against a
diagnosis, changing the diagnosis underneath it changes what the payer agreed to. Corrections
after submission are raised against the claim.

  Three surfaces on this page answer 404 in the service today: the visit-scoped clinical pair
  (`/api/v1/visits/{visit_id}/clinical`, which is also on the wrong version — the registered visits
  group is v2), the whole `/orders` prefix, and the whole `/referrals` prefix. Document generation
  under a visit is unbuilt too; `GET /api/v2/visits/{visit_ref}/documents` lists what is attached.

  Live at this stop: recording a diagnosis on the visit, episodes of care under
  `/api/v1/clinical/episodes-of-care`, and prescriptions. The reference marks each unbuilt operation
  where it appears, so a call you can run is distinguishable from one you cannot.

## Contribute the encounter

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/clinical" to="/rail-api/05-treat">
  Send the encounter as a FHIR bundle. It is validated, written to the clinical repository, and acknowledged.
</ApiRef>

The bundle is a transaction, so it is written whole or not at all. A validation failure
returns `issues[]`, and each entry names the index and the element that failed, so you can fix
the thing it names instead of re-reading the payload.

<Anatomy
  cards={[
    {
      title: "Encounter",
      required: ["status", "class", "period"],
      note: "One per visit. Its class matches the access_point the visit was opened with, so an outpatient visit does not contribute an inpatient encounter.",
    },
    {
      title: "Condition",
      required: ["code", "clinicalStatus"],
      note: "The same ICD-11 codes recorded above. Send them here too rather than expecting the rail to derive one from the other; the diagnosis call is a payer assertion, this is the clinical record.",
    },
    {
      title: "Observation",
      required: ["code", "value"],
      note: "Vitals, results and measurements, LOINC-coded. This is what makes the record longitudinal rather than a list of visits.",
    },
    {
      title: "DocumentReference",
      required: ["type", "content"],
      note: "Clinical notes: the history, the examination and the plan. Coded by note type so another system can find the discharge summary without reading all of them.",
    },
  ]}
/>

Send it as the encounter progresses, not once at the end. Another facility can already see an
acknowledged resource, while a bundle held back until discharge is a record that did not exist
at the moment somebody needed it.

<ApiRef method="GET" path="/api/v1/visits/{visit_id}/clinical" to="/rail-api/05-treat">
  Read back what this visit has written: the encounter and every resource under it.
</ApiRef>

Read it back rather than trusting your own copy. What the repository holds is what every
other reader sees, and what the documents below are rendered from.

## Encounters hang from an episode

A visit is one attendance. An episode of care is the thread that runs through several of
them, such as a pregnancy, a course of chemotherapy or the management of a chronic condition,
and it is the unit a clinician thinks in.

<ApiRef method="GET" path="/api/v1/clinical/episodes-of-care" to="/rail-api/05-treat">
  The episodes this patient has open, and what each one is about. `GET /{id}` reads one, and `GET /{id}/visit-summary` returns everything hanging off it.
</ApiRef>

<ApiRef method="POST" path="/api/v1/clinical/episodes-of-care" to="/rail-api/05-treat">
  Open an episode, or attach this visit to one that is already running.
</ApiRef>

<Wire
  rows={[
    { call: "Attach before you open", does: "Check for an open episode for this condition first. A new episode per visit produces a record that cannot answer \"is this working?\" about anything.", keep: "episode_id" },
    { call: "The episode may not be yours", does: "It can have been opened at another facility. Attaching to it is what makes a shared record longitudinal rather than a pile of visits.", keep: "managing_facility" },
    { call: "Closing is a clinical statement", does: "An episode is closed because the condition was resolved or care was transferred, not because the last visit ended. A closed one refuses new attachments.", keep: "status" },
  ]}
/>

Episodes are also what make sessions legible to a payer. A course of dialysis authorised as a
series at [06 · Preauthorize](/rail/stops/Preauth) is the same thing this records clinically:
one episode, many encounters.

## What was requested, and who performs it

Ordering and prescribing have the same shape. Something is requested here, performed
somewhere else, and answered back against the request. Neither one needs an integration with
the performer, because both of you are already on the rail.

<Wire
  rows={[
    { call: "Orders", does: "Labs, imaging, procedures. Panels come back expanded into their parameters, and results return against the order rather than into a mailbox you poll.", keep: "order_id" },
    { call: "Prescriptions", does: "Routed to the pharmacy the patient chooses. That pharmacy pulls it from its own inbox, so nothing is carried in on paper.", keep: "prescription_id" },
    { call: "Both directions", does: "The same calls make you a performer as well as a requester. A facility that only posts orders has built half of it.", keep: "the inbox" },
  ]}
/>

  The full set: ordering across facilities, returning results against the expanded parameters,
  routed prescriptions, partial fills and substitution rules.

## Where the patient goes next

A referral carries the record rather than a request to start again, and it carries the
authorisation the patient already gave you, so they do not travel to the receiving facility
just to authenticate a second time for the same episode.

  Hub and spoke without building hub and spoke: sending patients and specimens, accepting
  inbound referrals, and how one authentication at the source facility stands at the
  destination.

## The documents generate themselves

This is the first thing all of that recording pays back. Every field a discharge summary or a
claim form contains was recorded above, so the rail can render those documents from the
clinical data instead of asking somebody to write them.

<ApiRef method="POST" path="/api/v1/visits/{visit_id}/documents/generate" to="/rail-api/05-treat">
  Generate the documents this claim requires, from what has already been recorded.
</ApiRef>

Where a document cannot be produced, the response names the clinical elements that are
missing rather than form fields. The fix is to record the fact while the encounter is still
open, instead of typing it into a template at submission.

An HMIS that records clinically is paperless the day it connects, without building a document
editor, a template engine or a PDF pipeline.

  Generating the required set, rendering HTML for the screen and PDF for a signature, and why a
  stored PDF should never be your source of truth.

## Read it back

Reading is the other half of contributing. A clinician who can see that a patient was
treated for the same thing three weeks ago at another facility makes a different decision, and
does not repeat an investigation the payer has already paid for.

  The cross-facility timeline this section used to name — `/api/v1/beneficiaries/{unique_patient_id}/timeline` —
  is not a registered route, and neither is anything else under `/api/v1/beneficiaries`. The closest
  live call is `GET /api/v1/clinical/episodes-of-care/{id}/visit-summary`, which returns everything
  under one episode. It is episode-scoped rather than member-scoped, so it is not a substitute:
  build the read-back around episodes until a member-wide route exists.

  The proof collected at [03 · Consent](/rail/stops/Consent) authorises reading and billing a
  member's cover. It does not, on its own, authorise publishing the encounter beyond this
  facility or reading what other facilities recorded. That is a separate purpose, collected
  through the same flow, and neither direction is retroactive. A record contributed without it
  is refused with `CLINICAL_CONSENT_MISSING` rather than written and withdrawn later.

## What breaks here

<CostTable
  rows={[
    {
      where: "Submit",
      symptom: "\"The claim was rejected for an invalid diagnosis code\"",
      cause: "A grouping or chapter heading was sent instead of a codable entity, or a code from a superseded release. Filter the picker on codable and refresh against the current version.",
    },
    {
      where: "Submit",
      symptom: "\"Every code is valid and it still bounced\"",
      cause: "The diagnoses were not linked to interventions. The payer assesses the pair, and an unlinked diagnosis is not assessed at all.",
    },
    {
      where: "Preauth",
      symptom: "\"The request came back saying the procedure is not indicated\"",
      cause: "The diagnosis does not support the intervention under the payer's clinical rules. The detail block names both codes and the rule, and usually the diagnosis is under-specified rather than wrong.",
    },
    {
      where: "Treat",
      symptom: "\"We record the diagnosis at discharge\"",
      cause: "By then the clinician has gone and the coder is working from notes. Every downstream check that could have been answered in the room becomes a rejection instead.",
    },
    {
      where: "Treat",
      symptom: "\"The bundle was rejected and we do not know which part\"",
      cause: "Read issues[], where each entry carries the index and the element. A transaction bundle is not partially written, so nothing landed.",
    },
  ]}
/>

### Errors

| HTTP | `error` | When |
|------|---------|------|
| 422 | `DIAGNOSIS_REQUIRED` | Something downstream needs a diagnosis and the visit has none. |
| 400 | `DIAGNOSIS_CODE_INVALID` | Not in the current release, or not a codable entity. |
| 422 | `DIAGNOSIS_NOT_LINKED` | A diagnosis with no intervention, or an intervention with no diagnosis. |
| 422 | `DIAGNOSIS_INTERVENTION_MISMATCH` | The pair is refused by the payer's clinical rules. |
| 409 | `PRIMARY_DIAGNOSIS_CONFLICT` | More than one diagnosis ranked primary. |
| 409 | `DIAGNOSIS_LOCKED` | Amended after the claim was submitted. |
| 400 | `CLINICAL_BUNDLE_INVALID` | The FHIR bundle failed validation. |
| 403 | `CLINICAL_CONSENT_MISSING` | No consent covering clinical sharing. |

  Every code recorded at this stop comes from the terminology service. How to fetch one, cache
  it by version, and find out when the release moves.

## Next

**Next:** [06 · Preauthorize](/rail/stops/Preauth)

<AgentPrompt>{`You are integrating an HMIS with the Savannah unified payer rail.

Task: implement stop 05 (Treat).

1. Populate the diagnosis picker from
   GET /api/v2/clinical/diagnoses?version=serving&q=<query>.
   Offer ONLY entries flagged codable. Never ship a hard-coded ICD-11 list.
2. POST /api/v2/visits/{visit_ref}/diagnoses for each diagnosis, with
   icd11_code, description, rank and the intervention_code it justifies.
   Exactly one rank: "primary" per visit.
3. POST /api/v1/visits/{visit_id}/clinical with a FHIR transaction bundle:
   Encounter, Condition (the same ICD-11 codes), Observation (LOINC-coded
   vitals and results), MedicationRequest where prescribing happened. Send it
   as the encounter progresses, not once at discharge.
4. Read what the record already holds before the consultation and show it to the
   clinician. There is no member-wide timeline route today; the closest is
   GET /api/v1/clinical/episodes-of-care/{id}/visit-summary, which is scoped to
   one episode.
5. Attach the visit to an open episode of care where one exists
   (GET /api/v1/clinical/episodes-of-care) rather than opening a new episode
   per visit.
6. Build the request/perform pair in BOTH directions: post orders and
   prescriptions, AND poll the inboxes
   (the order inbox is not built yet; GET /api/v1/prescriptions is).
   Return results against the order's expanded_parameters.
7. Generate required documents with
   POST /api/v1/visits/{visit_id}/documents/generate instead of authoring them.
   On status "incomplete", record the clinical elements named in missing[].

Rules:
- The diagnosis-to-intervention link is not optional metadata. An unlinked
  diagnosis is not assessed, and the claim is rejected for having none.
- Cache codes by the version you resolved against, and re-validate when the
  release moves. A retired code fails at assessment, not at recording.
- Withdrawal is allowed until the claim is submitted and refused after it.
  Corrections after submission are raised against the claim.
- Clinical sharing is a separate consent purpose from payer consent. Collect it
  at stop 03; do not assume the payer proof carries it.
- On a referral, send authorization_ref and open the receiving visit by ACCEPTING
  the referral. Opening a visit directly forces the patient to authenticate twice.
- The bundle is a transaction: on failure nothing was written. Read issues[] and
  resend the whole bundle.`}</AgentPrompt>

---

## /rail/stops/Visit

# 04 · Visit

  Opening a visit touches no payer. It is an encounter and its account, written together in
  one atomic step, so the clinical record can start even while every payer is down.

## Why this stop exists

The visit is the container everything else attaches to. It is an **encounter first** —
conditions, observations, CDSS and generated documents hang off it — so it has to be
clinically native before it is ever billable.

Opening it is **local**. The rail writes an `Encounter` and an `Account` to its own clinical
store in a single atomic write and calls no payer. A visit with no covered lines is a purely
clinical visit and stays that way until one is added. Everything that touches a payer — the
authorization, the claim — happens on the lines you attach afterwards, and each is its own
answer that never un-opens the visit.

## Open the visit

<ApiRef method="POST" path="/api/v2/visits" to="/rail-api/04-visit" keep="visit_ref">
  Open an encounter and its account. `service_type` — OUTPATIENT or INPATIENT — is the only
  required field; it becomes the encounter's class and the service type every later
  authorization carries.
</ApiRef>

Identity and a service type are the whole of a clinical visit:

<Wireframe
  title="Open visit"
  actor="Front desk · Example Medical Centre (FID-47-105963-0)"
  rows={[
    [
      { label: "Patient", kind: "text", span: 2, from: "unique_patient_id", note: "Resolved at Identify" },
      { label: "Service type", kind: "field", span: 1, from: "service_type", note: "Outpatient · Inpatient" },
      { label: "Open visit", kind: "action", span: 1 },
    ],
    [
      { label: "Visit open — clinical", kind: "text", span: 4, tone: "positive", from: "visit_ref", note: "No cover attached yet. Conditions, observations and documents can start now; billing waits for a line." },
    ],
  ]}
  caption={<>A visit with no <code>service_lines</code> is clinical only. It needs no cover and no consent — nothing is being spent.</>}
/>

To open **against a cover**, send the committed `selection_ref` from [02 · Verify
cover](/rail/stops/Entitle), the `consent_ref` the consent ceremony minted (below), and one
or more `service_lines`, each naming its cover:

```json
{
  "unique_patient_id": "SIL-UPI-0091774",
  "service_type": "OUTPATIENT",
  "selection_ref": "4428ab22-…",
  "consent_ref": "1af5b95e-…",
  "service_lines": [
    { "code": "SHA-18-005", "cover": "SHA:zBxhrTRZ5_hYaO36" }
  ]
}
```

`selection_ref` is required once `service_lines` is present; `consent_ref` is required once a
selection is in scope. A clinical visit sends none of them.

## The consent it spends is a reference, not a proof

The consent ceremony happens end to end in the consent surface at [03 ·
Consent](/rail/stops/Consent) — the decision, the OTP or biometric, the verification. What
opening a visit receives is the **`consent_ref`** that ceremony produced: a redeemable
reference to a verified consent, not the raw proof. Open spends it once, by binding it to the
encounter.

  A point-of-care proof is single-use — its issuer admits exactly one redeemer. The ceremony
  is that redeemer; it mints a `visit_start` consent record and hands back a reference. Open
  redeems the *reference*, so a second open presenting the same one is refused
  `CONSENT_ALREADY_REDEEMED`. The proof itself is spent before it ever crosses this boundary.

## Service lines — the authorization unit

A service line is one intervention plus the cover it draws on. It is the unit a payer
authorizes and reserves balance against, and it is **payer-first**: the rail writes the line
as pending, asks the payer, and moves it to the answer the payer gave.

<ApiRef method="POST" path="/api/v2/visits/{visit_ref}/service-lines" to="/rail-api/04-visit" keep="service_line_ref">
  Authorize a cover for a named intervention. The same thing a line at open does, available
  after the fact — a visit opened clinical becomes billable here.
</ApiRef>

<Wireframe
  title="Authorize a service"
  actor="Front desk"
  rows={[
    [
      { label: "Intervention", kind: "field", span: 2, from: "code", note: "e.g. SHA-18-005" },
      { label: "Cover", kind: "field", span: 1, from: "cover", note: "One the selection names" },
      { label: "Authorize", kind: "action", span: 1 },
    ],
    [
      { label: "Authorized — KES 3,000 reserved", kind: "text", span: 4, tone: "positive", from: "the payer's answer", note: "The reserved amount is the payer's, never computed here." },
    ],
    [
      { label: "Refused — BENEFIT_EXHAUSTED", kind: "text", span: 4, tone: "negative", note: "The payer's own verdict, relayed word for word. The visit stays open; fix or drop this line." },
    ],
  ]}
  caption={<>Two outcomes worth designing for. A third — the payer being unreachable — leaves the line <em>pending</em> and is safe to retry; it is not a rejection.</>}
/>

Three outcomes, and only one is an error you resolve by changing the line:

<Wire
  rows={[
    { call: "authorized", does: "The payer reserved balance against the intervention", keep: "service_line_ref → add bill lines under it" },
    { call: "refused", does: "The payer declined; its machine code and reason are relayed verbatim", keep: "read the verdict, then fix or drop the line" },
    { call: "pending", does: "The payer did not answer; the line is kept durably and is retryable", keep: "PAYER_UNREACHABLE (502) → retry the same request" },
  ]}
/>

A refused or unreachable payer **never un-opens the visit**. The line carries the outcome;
the encounter and everything clinical proceed regardless.

## Record the practitioner

Who performed a service is stated once on the visit and referenced by every bill line, rather
than re-typed per line. The identification is checked against the Health Worker Registry when
it is added, so a bad registration number is refused at the desk — not when the payer's claim
bounces a week later.

<ApiRef method="POST" path="/api/v2/visits/{visit_ref}/practitioners" to="/rail-api/04-visit" keep="practitioner_ref">
  Record a performer. Verified against the registry under its regulator before it is stored.
</ApiRef>

It can happen at any time after open — nothing about opening a visit or authorizing a service
line waits on a clinician being known.

## Record a diagnosis

A diagnosis is a **clinical fact first** and a claim field second: it exists on visits that
never bill, it is recorded by a clinician rather than the desk, and it changes over a visit.
It is written to the clinical record — a `Condition` on the encounter — so CDSS, document
generation and the claim builder all read the same one.

<ApiRef method="POST" path="/api/v2/visits/{visit_ref}/diagnoses" to="/rail-api/05-treat" keep="diagnosis_ref">
  Record a diagnosis against the encounter. No cover appears here — a clinical diagnosis needs
  none, and a payer that requires one enforces that on the claim.
</ApiRef>

  Record the diagnosis in whatever system the clinician works in — ICD-11, ICD-10. Where a
  payer's claim wants the other system, the claim builder translates it at claim time. The
  desk never re-codes.

## What breaks here

<CostTable
  rows={[
    {
      where: "Visit",
      symptom: "\"It says consent required\"",
      cause: "The visit named a selection but no consent_ref. Run the consent ceremony first and pass the reference it returns.",
    },
    {
      where: "Visit",
      symptom: "\"Consent not redeemable\"",
      cause: "The consent expired, was already spent, or was taken for a different purpose. It is a fresh ceremony, not a retry — the redemption policy decides.",
    },
    {
      where: "Visit",
      symptom: "\"That cover is not in the selection\"",
      cause: "A service line named a cover the committed selection does not carry. A cover outside the selection needs its own selection and its own consent.",
    },
    {
      where: "Bill",
      symptom: "\"No authorized service line for this charge\"",
      cause: "A bill line drew on a service line that is pending or refused. There is no authorization for the charge to draw down until the line is authorized.",
    },
    {
      where: "Bill",
      symptom: "\"Practitioner not on the visit\"",
      cause: "The bill line referenced a practitioner_ref that was never added. Record the practitioner first; it is validated once, there.",
    },
  ]}
/>

### Errors

The rail's own refusals, before any payer is asked, carry a stable `error` code. Everything
else is the payer's verdict, relayed with its status intact.

| HTTP | `error` | When |
|------|---------|------|
| 404 | `PATIENT_NOT_FOUND` | The clinical store holds no patient under that identity. |
| 400 | `SERVICE_TYPE_INVALID` | `service_type` was not OUTPATIENT or INPATIENT. |
| 400 | `CONSENT_REQUIRED` | A selection is in scope but no `consent_ref` was sent. |
| 404 | `CONSENT_NOT_FOUND` | `consent_ref` resolves to nothing. |
| 409 | `CONSENT_NOT_REDEEMABLE` | Expired, consumed, or wrong purpose — the policy's own code is in `detail`. |
| 409 | `SELECTION_UNUSABLE` | The selection is unknown, inactive, or belongs to another patient. |
| 409 | `COVER_NOT_IN_SELECTION` | A line named a cover the selection does not carry. |
| 409 | `VISIT_NOT_OPEN` | The visit exists but no longer admits changes. |
| 409 | `SERVICE_LINE_MISSING` | A bill line named no authorized service line. |
| 409 | `SERVICE_LINE_NOT_AUTHORIZED` | The service line is pending or refused. |
| 409 | `PRACTITIONER_NOT_ON_VISIT` | The referenced practitioner was never added. |
| 422 | `PRACTITIONER_INVALID` | The registry did not resolve the identification under its regulator. |
| 502 | `PAYER_UNREACHABLE` | The payer did not answer; the line stays pending and the call may be retried. |

## Next

**Next:** [05 · Treat](/rail/stops/Treat) — the clinical record on the open encounter, then
[07 · Bill](/rail/stops/Bill) to charge under an authorized line.

---

## /rail/why/Benefit-Coordination

# Benefit coordination

  A patient rarely holds one cover. Most hold several, and deciding between them is not
  the clinician's job, nor the biller's.

## The situation

A teacher walks into a facility. She holds a public scheme through the national fund, a
second public scheme through her employer, and a private policy through her spouse's
employer. Her child, standing next to her, is a beneficiary on three of those four.

None of this is unusual. It is the ordinary case.

What is rare is a system that handles it well. The usual failure is quieter than a crash.
The software picks the wrong cover on its own, or it asks the front desk to pick while
giving them nothing to pick with, and the consequence lands weeks later as a rejected claim
or an out-of-pocket charge the member should never have paid.

## The shapes this takes

Multiple cover comes in a handful of recurring shapes, and which one you are in decides the
answer:

| Situation | Who goes first |
| --- | --- |
| Employer scheme alongside the national fund | The employer scheme; the national fund sits behind it |
| Two employers, one member | The primary employment; the second employer sits behind it |
| A child on both parents' schemes | The parent whose birthday falls earlier in the calendar year, which is not always the older parent |
| National fund plus a private top-up | Neither, in the ordinary sense. The two are complementary: the national fund carries inpatient, the top-up carries outpatient or dental. There is nothing to sequence |
| Retiree cover plus a spouse's active scheme | The spouse's active scheme; the retiree cover sits behind it |

Two rows deserve a second look. The birthday rule surprises almost everyone who meets it for
the first time, and you cannot derive it from anything on the member record you already hold.
The complementary case is the one where coordination is the wrong question, because those
covers divide by benefit rather than by order, and sequencing logic applied to them returns
a wrong answer with full confidence.

## What failure actually costs

When nobody sees the second cover, the money goes astray on a long and expensive loop:

<BuildSequence
  steps={[
    "The claim reaches the first payer with no mention of the second. It is paid in full.",
    "The same encounter reaches the second payer. It is also paid in full. The provider has now been paid twice for one visit.",
    "Months pass. An audit at the first payer surfaces the duplicate.",
    "A recovery request goes out, often on paper, to a counterpart with no shared record of the event.",
    "The dispute runs six to twelve months on who paid first and who should therefore recover.",
    "Recovery typically fails. Both sides write it off.",
  ]}
/>

Manual recovery of duplicate payments succeeds in well under a fifth of attempts. That is the
number sitting behind the phrase "claims get corrected later": mostly they are not corrected,
and somebody absorbs the loss.

The member pays as well, quietly. One episode of care draws down the balance on both covers,
nobody tells them, and they find out on the next visit when a benefit they should still have
is gone.

The rail changes one thing here. Eligibility drives the claim, instead of the claim going out
blind and being corrected afterwards.

## Why this is hard without a rail

Coordinating benefits means answering five questions, and each one lives in a different
system:

- Which covers are live today? Each has its own validity window and its own anniversary. One resets in October, another in July.
- Which of them are usable here? Empanelment is per facility, sometimes per practitioner, so a cover that is valid nationally can be unusable in this building.
- What does each one actually pay for? Not "outpatient" but the specific intervention, at this facility's tariff, with this facility's panel status.
- What is left on each? Balances are live, and they are often counts rather than money.
- Which should go first? And when the first is exhausted mid-visit, what happens to the rest of the bill?

Answering these directly means integrating with every scheme, holding a model of each
one's rules, and keeping that model current as the rules change underneath you.

## What the rail does

**It surfaces every cover in one shape.** One call after identity returns all of them, public
schemes and private policies together, with payer, member identifier, policy window and
current status normalised into a single list. That is enough to render a chooser without
waiting on a balance check for each cover.

**It filters to what is usable.** A cover that cannot be billed at this facility does not
appear in the list, so an empty result is an answer rather than something you have to go and
investigate.

**It makes the choice explicit and visible.** A person selects the cover, with the information
needed to choose. That selection is then frozen onto the visit, because it determines tariff,
limits, required documents and combination rules for everything that follows.

**It resolves entitlement against the chosen cover.** The shape is the same whichever payer it
is, so your screens do not branch.

## Principles worth building in

<BuildSequence
  steps={[
    "Store covers as a list, never as a field. A member with one cover today has three next month, and a single cover_id column is a migration waiting to happen.",
    "Never auto-select silently. If your system picks a cover without showing the operator why, a financial decision has moved somewhere nobody can audit.",
    "Re-check rather than cache. Eligibility is cheap by design, so re-run it when the desk changes its mind mid-conversation.",
    "Treat exhaustion as a workflow branch rather than an error. A benefit running out mid-visit is expected; what matters is that the operator sees it while the patient is still present.",
    "Keep the selection visible on every billing screen. The commonest coordination bug is a biller who does not know which cover they are billing against.",
  ]}
/>

## What is settled, and what is not

It is better to be straight about the boundary here than to sound complete.

**Settled today:** covers are surfaced together in one normalised list, filtered to what is
usable at this facility; the selection is explicit and is frozen onto the visit; entitlement
and billing resolve against that single selection; the claim is dispatched to the right
payer without you choosing an endpoint.

**Not settled today:** automatic sequencing across covers within a single visit. The shape it
would take is well understood: one encounter generating two claims, the first payer settling
its share, and the second claim carrying the first payer's remittance advice so the shortfall
is computed rather than guessed. What is not settled is that the API does this for you. Today
a visit runs against one selected cover. Where a second cover should pick up a shortfall, that
is currently a separate commercial and workflow decision.

If your product depends on automatic top-up behaviour, raise it now rather than designing
around an assumption. This is an active area, and integrator requirements shape where it
lands.

## Where this shows up on the rail

Coordination is not a stop of its own. Most of it sits at
**[02 · Verify cover](/rail/stops/Entitle)**, where covers are listed, chosen and expanded into
billable items, and the rest of it shows up at **[07 · Bill](/rail/stops/Bill)**, where the
patient's own share is separated from the payer's.

**Next:** [Ride the rail from the start](/rail/stops/Authenticate)

---

## /rail/why/The-Problem

# The problem, in one page

> Connecting to one payer is a project. Connecting to every payer your patients
> carry is a permanent department.

Most teams budget for the first sentence, and then the second one arrives.

## The shape of the work you think you are taking on

You already have a system, whether that is an HMIS, an ERP, a pharmacy platform or a lab
system. It knows who the patient is, what was done, and what it costs. Connecting it to a
payer looks, from the outside, like a mapping exercise: take what you have, reshape it, post
it somewhere, read back an answer.

If that were all of it, an integration would take a sprint.

## The shape of the work that arrives

Six things sit between "we have a patient and a bill" and "we have been paid", and every
one of them is a system with its own opinions.

**Identity takes more than a lookup.** An identifier without its type is just a number, and
it resolves to nothing. There are national IDs, CR numbers, birth notifications, birth
certificates, alien IDs, refugee IDs, passports, military IDs, membership numbers and phone
numbers. Some have been withdrawn. Published lists disagree with each other. A patient who
cannot be resolved fails in four different ways, and only one of them is genuine absence.

**Entitlement comes back as more than a yes.** It is a filtered set of interventions with
numbers attached, and almost everything you need attaches one or two levels lower in the
tree than you expect. Coverage is answered per scheme rather than per member, so a person
can hold several covers at once, with independent validity windows that reset on independent
anniversaries. Limits are frequently counts rather than money. Some benefits have no pool at
all.

**[Consent means proving the patient was there](/rail/stops/Consent).** It is a proof of presence, captured through hardware you do
not own, governed by policy that belongs to the facility rather than to you. Roughly three
adults in ten fail biometric matching, which makes the fallback path a main path rather than
an exception. So the interesting engineering sits in what happens when the happy path does
not happen, which is most of the time.

**[Authorisation bookends the visit](/rail/stops/Consent#two-consents-sometimes-three).** Opening and closing an encounter are both consent
events, and which factors are even offered depends on the card the member holds, the
payer, the benefit, the member's age, and whether the facility is whitelisted. Getting this
wrong does not raise an error where the mistake happened. It surfaces days later, as a claim
that cannot be finalised.

**Billing runs on combination rules.** Certain codes cannot co-occur. Accommodation is
per-diem and platform-generated, and a level change retires the affected lines instead of
editing them. Preauthorisation is a family of configuration hanging off the benefit tree
rather than a single boolean, and the clinical payload it requires differs by benefit type.

**Approval is also not payment.** A claim can be approved and still pay out nothing, because
payment hangs off banking records, invoice references and batch reconciliation that no part
of the clinical flow ever mentioned.

## Now multiply

Every paragraph above describes *one* payer world. Your patients do not carry one payer.

They arrive with public cover and private cover, sometimes both on the same visit,
sometimes with one topping up the other. Each world has its own identity vocabulary, its
own benefit shape, its own consent factors, its own claim lifecycle, its own remittance
schedule, its own idea of what a reservation is. One of them holds money against a benefit
in real time, while the other does not hold anything you can see.

Integrating with both directly means building and then *maintaining* two of everything: two
state machines, two error taxonomies, two sets of gotchas, two on-call rotations for the same
clinical event. It also puts other organisations' release schedules inside your own product
roadmap.

## Where the time goes

Not on the first integration. It goes on the second one, and on every change to the first.

The pattern repeats often enough to be worth naming. Teams ship a happy path quickly, then
spend months on the branches: the not-found that was really a type mismatch, the consent
failure that was really an expired licence, the rejected claim that was really a combination
rule, the three weeks live with no money that was really a missing bank record. Each one is
small on its own. Together they are the project.

The cost that hurts most is that none of this work is your product. It is the toll you pay
before you are allowed to work on your product.

## What follows

The rest of this section describes the alternative: one surface, one contract, one set of
instructions. The differences above still exist there, but they stop being yours to hold.

**Next:** [What the rail absorbs](/rail/why/What-The-Rail-Absorbs)

---

## /rail/why/What-The-Rail-Absorbs

# What the rail absorbs

> Every response tells you what to call next. You read the sequence off the responses instead of working it out yourself.

That is most of the design. The rest of this page fills it in.

## The trade

You keep your system. You keep your clinical workflow, your screens, your data model, your
release schedule. What you give up is having to know which payer world you are in.

You get one base URL, one identity vocabulary, one benefit shape, one consent flow, one
claim lifecycle and one remittance contract. Behind that, the public and private worlds
still differ as much as they ever did. The rail absorbs the difference rather than
forwarding it to you.

## What stops being yours

**Resolving identity across registries.** You send an identifier and its type, and you get
back a `unique_patient_id`. Everything after that keys off that one value: cover selection,
eligibility, authorisation, preauthorisation, reservation, billing and claims, whichever
payer ends up being billed. You never maintain a mapping table between identity systems,
because you only ever see one.

**Normalising benefits.** Public benefit trees and private benefit trees nest differently
and terminate in different vocabularies. What you receive is one benefit shape, with a
pointer to where its billable units live. The units underneath vary; the envelope around
them stays the same.

**[Every mode of consent, and the rules that decide between them](/rail/stops/Consent#one-stop-every-mode-of-consent).** Fingerprint, face, one-time code, guardian and national eKYC, each with its own vendor and device, plus the payer-specific rules for who may use which, which change without notice. Whether this member can use OTP,
whether biometrics is enforced at this facility, whether a guardian is required because the
member is a minor, whether a card-less path applies: all of that resolves through a decision
tree fed by the member, the facility, the payer and the benefit. You do not implement that
tree. You render what you are handed.

**Knowing which network you are on.** A payer is not a single set of mechanics. It reaches
you through a network, and it is the network, not the payer and not the scheme name on the
card, that decides how a member is identified, how eligibility is checked, which
authorisation modes are permitted, and how a finished claim is dispatched. Worse, the
binding sits at scheme level, so one insurer can span several networks, and you have to know
the network early in the visit or half the screens that follow are wrong. Off the rail, that
is a resolution step you own and a set of branches you maintain. On it, the network is
resolved when identity is, and never appears in your code.

**Knowing where a claim goes.** There is one close endpoint. The dispatch decision was made
back at cover selection and has been carried on every line since, so you never pick a
different endpoint per payer.

**The error taxonomy.** One error shape: `error`, `message`, `path`, `fix_stage`. Validation
returns every reason at once instead of one at a time, so you fix the whole batch in a
single round instead of queueing up repeat attempts.

## What stays yours

The rail does not make clinical judgements, and it does not pretend to.

Your system knows what clinical data belongs to a benefit type, and your system populates
it. The rail's job is narrower. Before anything is accepted, it checks that everything the
chosen benefit type requires on the current payer is present and well-formed, and if
something is missing it rejects with a message naming what is missing, rather than passing
something half-formed downstream.

Pricing, coding, care decisions and the record of what happened to the patient stay yours.
The rail carries them without authoring them.

## Where the differences went

The differences did not disappear. They moved.

Where payers genuinely behave differently, the rail surfaces that in place, inside the
single flow, at the moment it matters: one payer holds money against a benefit in real time
while the other tracks balance externally; one routes clinical sign-off through a separate
review product; one auto-reserves on approval while the other expects an explicit call.
Where you need to know, you are told, on the page you are already on.

What you are never asked to do is *choose a branch before you can start learning*. There is
no public track and no private track. There is one journey, and the variance sits inside it
as a footnote.

## The sequence

The whole surface is one sequence, and every scenario is this sequence with different
values in it:

<Mermaid chart={`flowchart LR
  A[Identify] --> B[Eligibility<br/>& cover] --> C[Consent] --> D[Visit]
  D --> T[Treat] --> E[Preauth] --> F[Bill] --> G[Submit] --> H[Reconcile]
`} />

There are two reorderings. Elective care moves preauthorisation before the visit. Emergency
reverses the first two steps, because treatment starts before anyone has established who is
being treated.

Learn the sequence once and every shape follows from it.

## How you are told what to do next

Every response carries `next_action`. Its `type` names the move, and where a call is
required it carries the endpoint too:

```json
{
  "next_action": {
    "type": "check_eligibility",
    "endpoint": "/api/v2/patients/SIL-UPI-0091774/eligibility/SEL-2026-08-14-0091/benefits"
  }
}
```

A client that switches on this one enum can drive the entire flow without any
chapter-specific logic, which is the point. The client is told its next move rather than
inferring it.

## What good looks like

You can tell this is working less from how quickly the integration went than from where a
refusal lands. It should happen at the front desk, in front of the patient, while it can
still be fixed, instead of arriving as a rejected claim a week later, when the patient has
gone home and the money has not.

**Next:** [Benefit coordination](/rail/why/Benefit-Coordination) · or skip ahead and
[start integrating](/rail/stops/Authenticate).

---

## /skills

# Skills for coding agents

If you build with a coding agent — Claude Code, Cursor, Copilot, Gemini CLI, Cline, Zed and
others — you can install what these docs know directly into it, rather than pasting links and
hoping the right pages get read in the right order.

A skill is a folder of instructions with a description that decides when it fires. Once
installed, your agent reaches for it on its own when you ask about a patient lookup or a KRA
code, and reads only the reference file that question needs.

## Install

```bash
npx skills add https://<this site>
```

That reads the index at [`/.well-known/skills/index.json`](/.well-known/skills/index.json) and
installs both skills into the project you run it in. No account, no repository access, nothing
to configure — the files are served from this site like any other page.

Add `-g` to install for your user instead of the current project, or `-y` to skip the prompts in
a script:

```bash
npx skills add https://<this site> -g -y
```

### What lands where

Skills go into `.agents/skills/<name>/`, with symlinks into each agent's own directory, so one
install serves every agent you use:

```
.agents/skills/
  slade360-advantage-rail/       SKILL.md + 4 reference files
  slade360-etims-invoicing/      SKILL.md + 2 reference files
.claude/skills/
  slade360-advantage-rail    -> ../../.agents/skills/slade360-advantage-rail
  slade360-etims-invoicing   -> ../../.agents/skills/slade360-etims-invoicing
skills-lock.json
```

`skills-lock.json` records a sha256 of each skill, so `npx skills update` can tell when this
site has published a newer version. Commit it if you want your team on the same revision.

## What you get

| Skill | Fires on | Carries |
|---|---|---|
| `slade360-advantage-rail` | Patient identity, cover, consent, visits, preauth, billing, claims, remittances | The ten stops in order, every operation with what to keep from it, all 68 error codes, and the token and facility-header rules |
| `slade360-etims-invoicing` | Tax invoices, KRA codes, VSCU and ETR devices, credit notes, ERPNext and CargoWise | The five-step invoice flow and every KRA code table, so a coded value is checked before it is sent |

## Keeping them current

```bash
npx skills update          # pull newer versions of everything installed
npx skills list            # show what you have
npx skills remove          # take one out
```

The skills are rebuilt on every deploy of this site, so an update gets you whatever the docs
currently say.

## Why they do not drift

The judgement in each skill is written by hand. Everything factual is generated, on every build,
from the same sources these pages read: the operation registry, the error dictionary, the eTIMS
spec and the KRA code tables.

So a skill cannot tell your agent something this site contradicts. In particular it carries the
`planned` flag: **20 of the rail's 44 operations are designed but not registered yet**, and each
answers 404 today. An agent working from the skill is told which, before it writes code against
one.

## Review before you trust them

Skills run with your agent's permissions, so read one before you rely on it — ours or anyone
else's. Every file is served plainly and is worth two minutes:

- [`slade360-advantage-rail/SKILL.md`](/.well-known/skills/slade360-advantage-rail/SKILL.md)
- [`slade360-etims-invoicing/SKILL.md`](/.well-known/skills/slade360-etims-invoicing/SKILL.md)
- [`index.json`](/.well-known/skills/index.json) — every file each skill owns

There is nothing executable in either: they are markdown instructions and markdown reference
tables, no scripts.

## If you would rather not install anything

Try one without installing it, which prints a prompt you can paste into any assistant:

```bash
npx skills use <this site>@slade360-advantage-rail
```

Or skip the tooling altogether. Everything the skills read is published on its own, and pointing
an assistant at [`/llms.txt`](/llms.txt) is enough for it to find the rest:

- [`/llms.txt`](/llms.txt) — the curated index of every page, in reading order
- [`/agent/operations.json`](/agent/operations.json) — the operation registry, with `planned`
- [`/terminology/rail-errors.json`](/terminology/rail-errors.json) — the error dictionary
- [`/specs/rail.json`](/specs/rail.json) and the other four OpenAPI documents

## Troubleshooting

**The command cannot find any skills.** Check that
[`/.well-known/skills/index.json`](/.well-known/skills/index.json) loads in your browser. Some
installers probe `/.well-known/agent-skills/index.json` instead; that path is served too, with
identical content.

**Your agent has the skill but never uses it.** A skill fires on its description, so ask in the
words it lists — name Advantage, the rail, eTIMS or a KRA code rather than asking generically
about an API.