Summarisation

POST /api/v1/summarisation/soapReturns a SOAP summary in JSON format based on a consultation transcription provided. The SOAP summary is formatted with the property keys: subjective , objective , assessment , and plan . patientData can be provided to incorporate additional structured patient data, such as past medical history, medications, or previous examination findings, into the SOAP note.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Codestring

Clinic code or identifier of the clinic making the API request.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Output-Languagestring

Language for the output response. Supported ISO 639-1 codes: en, fil, th, vi, id, ms, km, lo, my, tl, zh, ja, ko, ru, hi. Defaults to English if not specified.

REQUIREDX-Scrubs-<any-other-header>any

Other required headers depending on your organisation's provider ID.

BODY PARAMETERS

REQUIREDtranscriptstring

A consultation transcription. It does not need to follow the format of transcription endpoint.

OPTIONALpatientDataobject

An optional object containing structured patient data that will be incorporated into the output to provide additional context. This can include past medical history, medications, allergies, previous examination findings, or other relevant patient information.

Error Codes6 cases

Endpoint validation

400

Transcript is missing or invalid.

The JSON body is missing transcript, or transcript is empty.

Output language validation

400

Unsupported output language.

The X-Scrubs-Clinic-Output-Language header is present but does not match a supported language code.

Common HCI and authentication errors

400	Provider or HCI configuration is invalid.	Missing or unknown provider ID, no consultation method/auth flow configured for the provider, missing or malformed clinic code, invalid CA origin, or the provider clinic limit is reached.
401	Authentication failed.	API key credentials are missing or invalid, a root clinic/key cannot be found, or no API key is linked to the authenticated clinic.
429	Usage limit reached.	Free-tier usage is exhausted, or a non-root paid API key has expired.

Common runtime errors

500

Unexpected server or upstream failure.

Unhandled JSON/form parsing errors, AI provider failures, transcription provider failures, database errors, or unexpected response parsing failures.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

NodeJS

Python

CURL

1curl --location 'https://usescrubs.com/api/v1/summarisation/soap' \
2--header 'X-Scrubs-Clinic-Code: 00A123' \
3--header 'X-Scrubs-Clinic-Provider: SAMPLE_EHR_1' \
4--header 'X-Scrubs-Clinic-Output-Language: fil' \
5--header 'Content-Type: application/json' \
6--data '{
7    "transcript": "Hi, doctor, I have been having a headache for the past 1 week ..."
8}'

Sample Response

JSON

1{
2    "summary": {
3        "subjective": "1. Chief complaint: Nausea and loss of appetite ...",
4        "objective": "1. Abdominal examination: No significant findings ...",
5        "assessment": "Viral Gastroenteritis",
6        "plan": "1. Prescribe antiemetics for nausea and pain relievers ..."
7    }
8}

POST /api/v1/summarisation/pvsReturns a Patient Visitation Summary (PVS) in JSON format. This endpoint requires both a transcript and a summary from a consultation to generate a PVS. The PVS summary is formatted with the property keys: visit_summary , plans , and instructions .HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Codestring

Clinic code or identifier of the clinic making the API request.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Output-Languagestring

Language for the output response. Supported ISO 639-1 codes: en, fil, th, vi, id, ms, km, lo, my, tl, zh, ja, ko, ru, hi. Defaults to English if not specified.

REQUIREDX-Scrubs-<any-other-header>any

Other required headers depending on your organisation's provider ID.

BODY PARAMETERS

REQUIREDtranscriptstring

A consultation transcription. It does not need to follow the format of transcription endpoint.

REQUIREDsummarystring

A consultation summary. It does not need to follow the format of summaries from the summary endpoint but should resemble a SOAP note.

Error Codes7 cases

Endpoint validation

400	Transcript or summary is missing or invalid.	The JSON body is missing required summarisation inputs.
422	Transcript is too short.	The transcript has fewer than 20 words, usually indicating poor audio capture or an incomplete consultation.

Output language validation

400

Unsupported output language.

The X-Scrubs-Clinic-Output-Language header is present but does not match a supported language code.

Common HCI and authentication errors

400	Provider or HCI configuration is invalid.	Missing or unknown provider ID, no consultation method/auth flow configured for the provider, missing or malformed clinic code, invalid CA origin, or the provider clinic limit is reached.
401	Authentication failed.	API key credentials are missing or invalid, a root clinic/key cannot be found, or no API key is linked to the authenticated clinic.
429	Usage limit reached.	Free-tier usage is exhausted, or a non-root paid API key has expired.

Common runtime errors

500

Unexpected server or upstream failure.

Unhandled JSON/form parsing errors, AI provider failures, transcription provider failures, database errors, or unexpected response parsing failures.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

NodeJS

Python

CURL

1curl --location 'https://usescrubs.com/api/v1/summarisation/pvs' \
2--header 'X-Scrubs-Clinic-Code: 00A123' \
3--header 'X-Scrubs-Clinic-Provider: SAMPLE_EHR_1' \
4--header 'X-Scrubs-Clinic-Output-Language: fil' \
5--header 'Content-Type: application/json' \
6--data '{
7    "transcript":"Hi, doctor, I have been having a headache for the past 1 week ...",
8    "summary":"Patient reports having a headache for the past week ..."
9}'

Sample Response

JSON

1{
2    "pvs": {
3        "visit_summary": "During your visit today, we discussed ...",
4        "plans": "1. Tension Headache: This is a type of headache ...",
5        "instructions": "Please take the prescribed medications ..."
6    }
7}

POST /api/v1/summarisation/transform-noteTransforms a clinical summary according to either a template structure or custom instructions. This endpoint supports two mutually exclusive modes:

Template Mode: Provide either template or templateKey to transform the summary into the exact style and format of the given template. Headers and structure are preserved exactly as provided, while content areas are filled with relevant information from the summary. If no relevant information is found for a template section, it will be left blank.

Prompt Mode: Provide prompt with custom instructions to alter the note. The LLM will transform the summary according to your specific instructions rather than following a template structure.

Important: You must provide either (template or templateKey) OR prompt, but not both. The summary parameter is always required. Supports multi-language output via the X-Scrubs-Clinic-Output-Language header.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Codestring

Clinic code or identifier of the clinic making the API request.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

OPTIONALX-Scrubs-Clinic-Output-Languagestring

Language for the output response. Supported ISO 639-1 codes: en, fil, th, vi, id, ms, km, lo, my, tl, zh, ja, ko, ru, hi. Defaults to English if not specified.

REQUIREDX-Scrubs-<any-other-header>any

Other required headers depending on your organisation's provider ID.

BODY PARAMETERS

REQUIREDsummarystring

A consultation summary. It does not need to follow the format of summaries from the summary endpoint but should resemble a SOAP note.

OPTIONALtemplatestring

The template format/structure that the summary should be transformed into. Headers and structure will be preserved exactly as provided. Required if using template mode (cannot be used together with prompt).

OPTIONALtemplateKeystring

An alternative to template - a key identifier to utilise a known template type. Required if using template mode and template is not provided (cannot be used together with prompt).

OPTIONALpromptstring

Custom instructions for transforming the summary. When provided, the note will be transformed according to these instructions. Required if using prompt mode (cannot be used together with template or templateKey).

Error Codes8 cases

Endpoint validation

400	Summary or transformation mode is invalid.	summary is required. Provide either template/templateKey or prompt, but not both.
400	templateKey is invalid.	templateKey must be a non-empty string containing only letters, numbers, underscores, or hyphens.
404	Template key was not found.	A templateKey was supplied but no matching consultation template exists.

Output language validation

400

Unsupported output language.

The X-Scrubs-Clinic-Output-Language header is present but does not match a supported language code.

Common HCI and authentication errors

400	Provider or HCI configuration is invalid.	Missing or unknown provider ID, no consultation method/auth flow configured for the provider, missing or malformed clinic code, invalid CA origin, or the provider clinic limit is reached.
401	Authentication failed.	API key credentials are missing or invalid, a root clinic/key cannot be found, or no API key is linked to the authenticated clinic.
429	Usage limit reached.	Free-tier usage is exhausted, or a non-root paid API key has expired.

Common runtime errors

500

Unexpected server or upstream failure.

Unhandled JSON/form parsing errors, AI provider failures, transcription provider failures, database errors, or unexpected response parsing failures.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

NodeJS

Python

CURL

1curl --location 'https://usescrubs.com/api/v1/summarisation/transform-note' \
2--header 'X-Scrubs-Clinic-Code: 00A123' \
3--header 'X-Scrubs-Clinic-Provider: SAMPLE_EHR_1' \
4--header 'X-Scrubs-Clinic-Output-Language: en' \
5--header 'Content-Type: application/json' \
6--data '{
7    "summary": "Patient reports headache for past week, worsening. Normal vitals. Assessment: tension headache. Plan: ibuprofen, stress management.",
8    "template": "SOAP NOTE\n\nDate: ___________\nProvider: ___________\n\nCHIEF COMPLAINT:\n___________\n\nHISTORY:\n___________\n\nASSESSMENT:\n___________\n\nPLAN:\n___________"
9}'

Sample Response

JSON

1{
2    "transformed_note": "EMERGENCY DEPARTMENT SOAP NOTE\n\nDate: 2024-01-15\nProvider: Dr. Smith\n\nCHIEF COMPLAINT:\nHeadache for 1 week\n\nHISTORY OF PRESENT ILLNESS:\nPatient reports headache for past week, gradually worsening...\n\nASSESSMENT AND PLAN:\n1. Tension headache - ibuprofen and stress management\n2. Follow up if symptoms worsen\n\nProvider: Dr. Smith"
3}