Developers: the HIS vendor API

Three rules the API is built around

1. The doctor signs. There is no request that signs a summary. The treating doctor signs in Kural discharge summaries with their own Google account, and you are told when they have.
2. The doctor says who may connect. You reach a doctor only with a one-time code the doctor makes in their own account. Either of you can end the connection, and then you no longer reach that doctor's summaries.
3. The patient's numbers: the IP number and the UHID, both optional. demographics.ip_number, or demographics.ip_number_not_issued: true where the hospital issues none; and demographics.uhid (since 27 Sep 2026), printed on the PDF beside the IP number. Both are letters, digits, space, / . -, up to 30. There is no field for a phone number, and an unknown field is refused. Keep your own mapping from the summary id you get back to your record.

Keys

Base address: https://review.kural.health/v1. Send the key on every request:

Authorization: Bearer dcsk_test_3f9a0c1b2d4e5f60_…

• A key starts dcsk_test_ or dcsk_live_, and works only on a service in that mode.
• A key is shown once, when it is made. It is stored only as a hash, so a lost key is replaced, not recovered.
• POST /v1/keys/rotate returns a new key; the old one keeps working for 24 hours.
• Up to 120 requests a minute per key. Above that the answer is 429 with Retry-After. The limit is counted per server instance, so treat it as approximate.
• GET /v1/account shows your name, the summaries you have left and when they expire, and the key in use.

Linking a doctor

1. The doctor, already verified in Kural discharge summaries, opens their account and makes a connection code. It looks like ABCD-EFGH-JKMN, works once, and lasts 30 minutes.
2. You send it: POST /v1/doctors/links with {"code": "ABCD-EFGH-JKMN"}.
3. The answer is the link, with the doctor's name, registration number and council. Use its id as doctor_link_id.

GET /v1/doctors/links lists your links. DELETE /v1/doctors/links/{id} ends one. A link the doctor ended shows "status": "revoked".

Summaries

The form (contract version 1)

Only these fields are accepted. Dates are YYYY-MM-DD; text fields are length-limited.

A summary can be saved half-filled. To draft, it needs the patient's name, the admission date, the diagnosis, and a route for every medicine.

Drafting

POST /v1/summaries/{id}/generate answers 202 with a draft_job. Then either poll GET /v1/summaries/{id} until draft_job.status is done or failed, or wait for a webhook.

• Refusals that cost nothing come back at once, not as a job: a missing field is 422 contract_incomplete with the list; a signed summary is 409.
• A second request while a job is running returns that job. It does not draft twice.
• Each draft uses one of your summaries. A draft that fails uses nothing: the job ends failed with its reason, and anything taken is returned.
• Summaries you have not used expire on the date shown in GET /v1/account.

Webhooks

Intelliwise registers your webhook address (https) and gives you a signing secret once. Events:

The body carries ids and states only, never clinical text. Fetch the summary with your key.

{ "id": "evt_…", "type": "summary.signed", "created_at": "2026-09-16T08:30:00.000Z",
  "data": { "summary_id": "42", "doctor_link_id": "7", "status": "signed" } }

Check every delivery before you trust it. The DCS-Signature header is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of t + "." + raw body with your secret:

const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
const ok = fresh && crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'));

• Answer with any 2xx within 10 seconds. Anything else is retried after 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours, then marked failed.
• The same event can arrive twice. Use DCS-Event-Id to ignore repeats.

The embedded page

For a hospital system without its own discharge page. The doctor fills the form, drafts, edits and saves inside your system; you pay for the drafts.

1. Intelliwise registers the origins allowed to frame the page, for example https://his.example.in. Other sites cannot frame it.
2. Your server calls POST /v1/embed-sessions with {"doctor_link_id"}, and optionally "summary_id" to reopen one. The answer has a url and expires_at (60 minutes).
3. Put the URL in an iframe as it is. The token is in the part after #, which browsers never send to a server.

<iframe src="https://review.kural.health/embed/v_…#token=…"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
  style="width:100%;height:100vh;border:0"></iframe>

The page cannot sign. Its "Sign in DCS" button opens Kural discharge summaries in a new window, where the doctor signs in and signs; that is why the frame needs allow-popups. The page shows the signature when it is done, and you receive summary.signed.

Errors

Every error is JSON with an error code, sometimes with facts beside it. A summary or link you cannot reach is always 404, so ids reveal nothing.