Skip to main content

​
Events

The Stitch component will communicate with your frontend application using Client-Side Events (Javascript Events in the Web Component SDK and React Events in React Native SDK). Stitch SDKs 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": "",

      "external_id": "",
      "external_state": "",

      //only populated when reconnect_org_connection is present
      "org_connection_id": "",
  }
}
​
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.)TEFCA When connecting in TEFCA mode, this field may be omitted.
​
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 institutionTEFCA When connecting in TEFCA mode, this field may be omitted.
​
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 institutionTEFCA When connecting in TEFCA mode, this field may be omitted.
​
org_connection_id
string
Organization Connection Id is a unique identifier for the connection between the patient and the organization.Reconnect Will only be present if the reconnect-org-connection-id parameter was provided to the stitch html element.
​
external_id
string
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
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": "",
      "scope": "",
      "consent_expires_at": ""
  }
}
​
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
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.)TEFCA When connecting in TEFCA mode, this field may be omitted.
​
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 institutionTEFCA When connecting in TEFCA mode, this field may be omitted.
​
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 institutionTEFCA When connecting in TEFCA mode, this field may be omitted.
​
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.
​
scope
string
(Optional) The OAuth2 scope that was granted by the patient during the connection process. See https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.htmlOnly some EHRs will provide this information. For EHRs that do not provide this information, this field will be omitted.TEFCA When connecting in TEFCA mode, this field will always be present and will contain the value patient/*.read.
​
consent_expires_at
string
(Optional) This will be an RFC3339 timestamp which will specify when the patient’s consent to share data with your application will expire.Only some EHRs will provide this information. For EHRs that do not provide this information, this field will be omitted.
​
tefca_directory_id
string
(Optional) The TEFCA Directory ID of the health system that the patient connected to.TEFCA When a health system is connected via TEFCA, this field will be present and will contain the TEFCA Directory ID of the health system.Similar to the brand_id, this value can be used to retrieve branding information about the institution. Prefer the brand_id when both values are present.

​
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": ""
  }
}
TEFCA This event will not be emitted when connecting in TEFCA mode.
​
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
​
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.

​
widget.complete

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.

​
widget.config_error

This event is emitted when the widget is not correctly configured, such as when an invalid public-id is provided, or “tefca” mode is enabled without a paid plan. 
{
  "api_mode": "test",
  "event_type": "widget.config_error"
}
Ensure that the public-id and other required parameters are correctly configured in the widget to avoid this error.

​
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": ""
  }
}