Web Widget

The BiomAPI Web Widget lets a browser application import reviewed biometry data without building its own upload or review UI. It opens the full BiomAPI web app in a large popup, including single-file upload, BiomPIN retrieval, History, Transcribe, editing, and the original-report comparison.

Usually simpler for browser integrations

If your application needs to autofill a browser form with reviewed biometry data, start with the Web Widget. BiomAPI supplies the complete user interface and handoff. Use the REST API when you need a custom interface, server-side processing, automation, or direct request control.

The widget never sends clinical data automatically. The green status bar shows the integrator name, and the user must press Send. Cancel and native popup closure return null. The result card’s Close action only clears the current result.

Open the live demo to try the widget, copy links with or without identity, and automatically import fragment links.

Quick start

Load the zero-dependency Browser SDK from the BiomAPI deployment. It also provides attributed BiomPIN retrieval, sharing, fragment consumption, identity context, and optional history:

<script src="https://biomapi.com/static/js/biomapi-sdk.js"></script>

Open it directly from a user action so the browser does not block the popup:

<button id="import-biometry" type="button">Import from BiomAPI</button>

<script>
document.getElementById('import-biometry').addEventListener('click', async () => {
  try {
    const response = await BiomAPI.widget.open({
      integrator: {
        id: 'example-ehr',
        name: 'Example EHR'
      }
    });

    if (response) {
      fillBiometryForm(response.data);
    }
  } catch (error) {
    console.error(error.code, error.message);
  }
});
</script>

integrator.id is a stable lowercase identifier using letters, digits, ., _, or -, up to 64 characters. The biomapi.* namespace is reserved by convention for official BiomAPI clients, without providing authentication. integrator.name is the human-readable name shown in the green bar.

Result

BiomAPI.widget.open() resolves to the reviewed StandardAPIResponse after the user presses Send. Cancel and native popup closure resolve to null.

Sent result:

{ /* StandardAPIResponse */ }

Cancelled result:

null

It reports a BiomAPI.widget.BiomAPIWidgetError when the popup is blocked, the integration options are invalid, or the connection fails. Invalid integrator options throw synchronously; popup and connection failures reject the promise. The error’s code is POPUP_BLOCKED, INVALID_INTEGRATOR, CONNECTION_TIMEOUT, or CONNECTION_FAILED.

Only one widget session can be active per page. Calling open() again focuses the existing popup and returns the same promise.

Patient identifiers

BiomAPI never returns a full patient name: the schema converts it to uppercase initials or an acronym. When patient initials or an ID are available in the current browser, the BiomPIN card shows the identifiers beside an Anonymous choice. This is a browser-side choice applied to the widget response:

• Identifiers included returns the reviewed StandardAPIResponse with the available initials and patient ID.
• Anonymous returns the same response with only data.patient.name and data.patient.id set to null.

Patient initials and ID may exist in browser-local context, but they are removed before a BiomPIN payload is encrypted and stored. They are never stored in the BiomPIN database. See the Privacy Policy for the complete processing and browser-storage boundaries.

Delivery and security

The SDK and widget use a popup-scoped MessageChannel. Both sides validate the window, protocol version, and origin. The widget confirms acceptance over that channel; its initial ready message alone does not end the 15-second connection timeout. Reloading the popup requires a fresh connection. The opening page acknowledges receipt of the reviewed result before BiomAPI closes the popup. Production integrators must use HTTPS.

BiomAPI also applies the platform’s existing security and data-minimization controls:

• Clinical data is returned to the integrator only after the user presses Send.
• Raw uploaded files are not stored after processing.
• Stored BiomPIN payloads exclude patient initials and ID, use AES-256-GCM encryption, and cannot be decrypted without the numeric PIN, which is never stored. See the BiomPIN documentation.
• Operational analytics exclude uploaded files, response payloads, clinical measurements, patient demographics, initials, patient IDs, and notes.

See the Privacy Policy for processing and retention details.

The widget automatically adds these optional headers to its process and retrieve requests:

Header	Value
X-BiomAPI-Integrator-ID	The configured integrator.id
X-BiomAPI-Integrator-Origin	The validated opener origin

When analytics is enabled, the server records only integrator_id and the origin hostname as integrator_origin_host on the existing biom_process or biom_retrieve event. These are soft attribution fields, not authentication. No separate widget Send event is emitted.

Tips

• Consider using BiomAPI purple (#625bb1) with white text for the primary button.
• Do not autofill on popup close. Autofill only when open() returns a response.
• Cancel and closing the popup return no data.
• Alternatively, integrate BiomAPI through its REST API.

Response schema

The resolved response is the same StandardAPIResponse returned by the REST API. Integrators should consume the documented schema rather than DOM content from the popup.