This documentation is for Stitch.js (v3) SDK, which is now the recommended version for integrating Fasten Connect into your application. If you need access to the previous version, please see the v1 documentation.This version includes a new API, compatibility with additional frontend frameworks (Next.js, React, Native, etc), improved performance, and additional features.v3 also introduces a number of breaking changes. Please see v3/update-guide for more information.The v1 Web Component is in maintenance mode and will no longer receive updates (outside of security fixes). Please update your code to use the new version.

<fasten-stitch-element
    public-id="public_test_123456324234234"
    external-id="user_12345"
>
</fasten-stitch-element>

<script type="application/javascript">
    const el = document.querySelector('fasten-stitch-element');
    el.addEventListener('eventBus', (event) => console.log(event.detail));
</script>

public-id

string

required

This must be your API public ID. You can find it in your Fasten Connect Portal.

reconnect-org-connection-id

string

(Optional) Useful when the patient connection credentials are invalid (due to expiration or revocation). Providing this reconnect-org-connection-id allows Fasten to reauthenticate the Patient and store their new credentials.

external-id

string

(Optional) An Opaque identifier, used to identify the patient in your system. This value will be returned in the response.

search-only

boolean

(Optional) If set to true, the stitch component will only show the search box and will not prompt the patient to verify their email address.

search-query

string

(Optional) Prepopulate the search box with a query.

show-splash

boolean

(Optional) Show a splash page introduces Fasten Connect and displays your privacy policy & terms to the patient before they begin the connection process.

Show example

static-backdrop

boolean

(Optional) If set to true, the stitch component will not close when the user clicks outside of the modal. This is useful for cases where you want to keep the modal open until the user explicitly closes it.

event-types

string

(Optional) By default the following standard events are always emitted:

patient.connection_pending
patient.connection_success
patient.connection_failed
widget.complete.

If you would like to recieve the optional events listed below, you must set the event-types parameter to a comma-separated list of event types.

search.query: This event is emitted when the patient searches for a healthcare institution in the Fasten Connect catalog.

Events

Unlike the previous version of the stitch component, the new version does not support redirect mode.

The Stitch component will communicate with your frontend application using JavaScript events. Stitch widget will generate a variety of events that you react to via an Event Listener (addEventListener()).

<script type="application/javascript">
    const el = document.querySelector('fasten-stitch-element');
    el.addEventListener('eventBus', (event) => console.log(event.detail));
</script>

patient.connection_pending

This event is emitted when the patient has begun the process to connect and the popup window has closed.

{
  "api_mode": "live",
  "event_type": "patient.connection_pending",
  "data": {
      "public_id": "",
      "brand_id": "",
      "portal_id": "",
      "endpoint_id": "",

      //only populated when reconnect_org_connection is present
      "org_connection_id": "",
      "external_id": "",
      "external_state": ""
  }
}

endpoint_id

string

required

Endpoint Id is a unique identifier for the endpoint that the patient has connected to. This value can be used to retrieve metadata about the endpoint (e.g. name, description, endpoint url information, etc.)

portal_id

string

required

Portal Id is a unique identifier for the Portal that the patient has connected to. This value can be used to retrieve branding information about the institution

brand_id

string

required

Brand Id is a unique identifier for the Brand that the patient has connected to. This value can be used to retrieve branding information about the institution

org_connection_id

string

Organization Connection Id is a unique identifier for the connection between the patient and the organization. You must store this value in your system to identify the patient in future API calls.

external_id

string

(Optional) An Opaque identifier, used to identify the patient in your system. This value will be only be returned if it was previously provided to the stitch html element.

external_state

string

(Optional) An Opaque identifier, used to identify the connection request. This value will be only be returned if it was previously provided to the stitch html element.

patient.connection_success

This event is emitted when the patient has successfully connected to a single health system.

In most cases you’ll want to listen to the widget.complete event instead of this one, as it will contain all the successful connections in a single event.

{
  "api_mode": "live",
  "event_type": "patient.connection_success",
  "data": {
      "org_connection_id": "",
      "endpoint_id": "",
      "brand_id": "",
      "portal_id": "",
      "connection_status": "",
      "platform_type": "",
      "request_id": ""
  }
}

org_connection_id

string

required

Organization Connection Id is a unique identifier for the connection between the patient and the organization. You must store this value in your system to identify the patient in future API calls.

endpoint_id

string

required

portal_id

string

required

Portal Id is a unique identifier for the Portal that the patient has connected to. This value can be used to retrieve branding information about the institution

brand_id

string

required

Brand Id is a unique identifier for the Brand that the patient has connected to. This value can be used to retrieve branding information about the institution

connection_status

string

required

The status of the connection. Possible values are authorized, rejected.

platform_type

string

required

An identifier for the EHR type associated with the connected endpoint.

request-id

string

An correlation id. This should be sent with any support ticket queries to the Fasten Connect support team.

patient.connection_failed

This event is emitted when an error occurred while the patient attempted to connect to their health system. The popup window has closed.

{
  "api_mode": "live",
  "event_type": "patient.connection_failed",
  "data": {
      "endpoint_id": "",
      "brand_id": "",
      "portal_id": "",
      "connection_status": "",
      "platform_type": "",
      "request_id": "",
      "error": "invalid_request",
      "error_description": "The request is missing a required parameter",
      "error_uri": ""
  }
}

endpoint_id

string

required

portal_id

string

required

Portal Id is a unique identifier for the Portal that the patient has connected to. This value can be used to retrieve branding information about the institution

brand_id

string

required

Brand Id is a unique identifier for the Brand that the patient has connected to. This value can be used to retrieve branding information about the institution

connection_status

string

The status of the connection. Possible values are authorized, rejected.

platform_type

string

An identifier for the EHR type associated with the connected endpoint.

request_id

string

required

Every error will have a unique request_id. When communicating with the Fasten Health development team, please provide the request_id, as it will make the debugging process much easier.

error

string

required

The error parameter will contain a short string representing the error that occurred.For errors that occurred on the health system side, the possible values are:

invalid_client
invalid_grant
unauthorized_client
unsupported_grant_type
invalid_scope

For errors that occurred on the Fasten Health side, the possible values are:

fasten_unauthorized_client
fasten_invalid_request
fasten_server_error
fasten_token_exchange

error_description

string

required

The error_description parameter can only include ASCII characters, and will be a sentence or two at most describing the circumstance of the error.

error_uri

string

The error_uri is an optional url parameter that may contain a link to the EHR’s API documentation for more information.

This event is emitted when the patient has finished connecting each healthcare institution and has closed the modal.

{
  "api_mode": "live",
  "event_type": "widget.complete",
  "data": [{
      "org_connection_id": "",
      "endpoint_id": "",
      "brand_id": "",
      "portal_id": "",
      "connection_status": "",
      "platform_type": "",
      "request_id": ""
  }]
}

The data field is an array of objects, each object representing a successful connection to a healthcare institution. See patient.connection_success for the details of each object.

search.query (optional)

This event is emitted when the patient searches or a health care institution in the Fasten Connect catalog. This event is opt-in, and must be configured by setting the event-types="search.query" parameter to the stitch Web Component.

{
  "api_mode": "live",
  "event_type": "search.query",
  "data": {
      "query": "search term",
      "timestamp": 1674123456,
      "filter": {
        "locations": ["CA"]
      },
      "results": {
        "total": 4
      },
      "external_id": ""
  }
}

Javascript API

The stitch Web Component has a Javascript API that can be used to manipulate the modal popup.

Methods

show()

Shows the modal popup.

  window.addEventListener('DOMContentLoaded',function () {
    //show the modal using the element selector.
    document.querySelector('fasten-stitch-element').show();
  });

hide()

Hide the modal popup.

  window.addEventListener('DOMContentLoaded',function () {
    ...

    //hide the modal using the element selector.
    document.querySelector('fasten-stitch-element').hide();
  });

Styling

Styling the stitch Web Component button is possible using CSS. You can target the component using the 'fasten-stitch-element' tag and select internal elements to apply custom styles.

  <style>
    fasten-stitch-element > button {
      background-color: green !important
    }
  </style>

The !important flag may be required to override the default styles.

The fasten-stitch-element is made up of a button, modal and iframe. As such, you can target the button and modal elements to apply custom styles, but you will not be able to style any content within the iframe.

Customizing Button Text

You can customize the text displayed on the “Share Records” button by adding your desired text between the opening and closing <fasten-stitch-element> tags. For example:

<fasten-stitch-element
    public-id="public_test_123456324234234"
    external-id="user_12345"
>
    Connect My Health Records
</fasten-stitch-element>

In this example, the button will display the text “Connect My Health Records”. Replace the text with any message that fits your use case.

Avoid using overly long text or HTML tags, as this may affect the button’s appearance and functionality.

If no text is provided, the default button text will be used.

​Events

​patient.connection_pending

​patient.connection_success

​patient.connection_failed

​widget.complete

​search.query (optional)

​Javascript API

​Methods

​show()

​hide()

​Styling

​Customizing Button Text

Events

patient.connection_pending

patient.connection_success

patient.connection_failed

widget.complete

search.query (optional)

Javascript API

Methods

show()

hide()

Styling

Customizing Button Text