Launch parameters

These fields describe the encounter the panel is opened for. In the secure modes they go in the SAHL_IFRAME_INIT payload. In URL mode they go in the query string.

Field	Type	Required	Description
access_token	string	Yes¹	Access token from /users/login.
token	string	Yes²	Signed assertion (Secure JWT handshake only).
px_id	string	Recommended	Your patient identifier (MRN).
ex_id	string	Recommended	Your encounter or visit identifier. Together with px_id, it links the Sahl AI session to the chart, so reopening the same encounter resumes the same session.
ux_id	string	Optional	Your user (clinician) identifier.
age	integer	Optional	Patient age in days. Improves codification accuracy, including age-specific ICD-10 rules. See Age format.
gender	string	Optional	male or female. Other values are ignored.
cta	string	Optional	Label for the send button, for example Send to WebEMR. Up to 50 characters.
theme	string	When issued	URL only, in every mode. Selects your organization's branding and response mapping. Sahl AI tells you the value. Case-insensitive.

¹ /iframe and /iframe-secure. ² /jwt-auth-secure.

Unknown fields are ignored, so adding your own fields will not break the integration.

Age format

Send age as a whole number of days, worked out from the patient's date of birth on the day of the encounter. Days are precise enough for neonatal and paediatric coding rules, which a whole number of years cannot express.

Patient	age
10 days old	10
About 6 months old	182
10 years old	3652
45 years old	16436

function ageInDays(dateOfBirth, onDate = new Date()) {
  const dob = Date.UTC(dateOfBirth.getFullYear(), dateOfBirth.getMonth(), dateOfBirth.getDate());
  const day = Date.UTC(onDate.getFullYear(), onDate.getMonth(), onDate.getDate());
  return Math.floor((day - dob) / 86_400_000);
}

Days, not years

A value such as 45 is read as 45 days, not 45 years. Always convert from the date of birth. If you do not know the age, leave the field out rather than sending an estimate.

Organization themes

A theme sets the panel's branding and, where agreed, a custom response mapping. With a mapping, the write-back payload uses your field names, your code sets and your picklist values, such as frequency, route and duration. Mappings are built by Sahl AI from the master lists and sample payloads you provide. Contact your Sahl AI integration lead to request one.

Without a theme you receive the standard payload.