Guides

Widget integration

The end-to-end flow — launch the widget for an encounter and receive a signed note callback.

The widget is the fastest way to add Dorascribe to your product. You launch it for a patient encounter with the context you already have, the clinician records the visit, and the finished note is delivered back to your server.

1. Initialize a session

Call /widget/init with the patient context, the note template, and a callback URL. Authenticate with your organization API key (see Authentication).

Shell

curl -X POST https://api.dorascribe.ai/api/v1/widget/init \
  -H "X-API-Key: org_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_name": "Jordan Rivera",
    "patient_age": 34,
    "patient_pronoun": "They",
    "language": "Spanish",
    "language_code": "es",
    "output_language": "English",
    "output_language_code": "en",
    "template_id": 12,
    "output_format": "html",
    "callback": "https://your-app.com/api/dorascribe/note"
  }'

Init parameters

Field	Description
`patient_name`, `patient_age`, `patient_pronoun`	Patient context, passed straight through so the clinician never re-enters it.
`language` / `language_code`	The language the encounter is conducted in (ISO 639-1).
`output_language` / `output_language_code`	The language the note is written in — can differ from the input.
`template_id`	Which note template to generate. List options via `/widget/all-templates`.
`output_format`	Note format, e.g. `html`.
`callback`	HTTPS URL that receives the finished note.

On Prepaid Credits you also pass an access token in the body; on Pay-as-You-Use it is optional. init returns a widget URL you load in an iframe.

2. Capture and generate

The clinician records the consultation in the widget. Dorascribe transcribes it and generates a structured note from your chosen template. When ICD-10 coding is enabled, each diagnosis is returned with its code and description.

3. Receive the callback

When the note is ready, Dorascribe POSTs it to your callback URL and does not store it — your system is the record of truth. The callback URL must use HTTPS and should return a 2xx status on success.

Every callback is signed with HMAC-SHA256. These headers are included:

Header	Description
`X-Dorascribe-Signature`	HMAC-SHA256 of the raw payload, keyed with your API key.
`X-Dorascribe-Timestamp`	Unix timestamp when the callback was sent.
`User-Agent`	`Dorascribe-Callback/1.0`

Verify the signature

Always verify the signature before trusting a callback:

PHP

$signature = $request->header('X-Dorascribe-Signature');
$payload   = $request->getContent();
$expected  = hash_hmac('sha256', $payload, env('DORASCRIBE_API_KEY'));

if (!hash_equals($expected, $signature)) {
    return response()->json(['error' => 'Invalid signature'], 401);
}

$data = json_decode($payload, true);
// $data['raw_transcription'], $data['transcription'],
// $data['template_content'], $data['icd_codes'], $data['metadata'] …

The payload carries the raw transcription, the formatted note, the template content, any ICD-10 codes, and the patient metadata you passed to init — so the note maps straight back to the right encounter. See the API Reference for the complete schema.