# Authentication
Source: https://docs.connect.fastenhealth.com/api-reference/authentication
Documentation for the Fasten Connect API
## Authentication
All sensitive API endpoints require authentication using the Public ID & Private Key generated in the Fasten Connect dashboard.
This is done using [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), where the Public ID is the username and the Private Key is the password.
Remember, when generating the Basic Auth header manually, the Public Id and Private Key must be concatenated with a colon `:` and then base64 encoded.
The resulting string should be prefixed with `Basic ` and included in the `Authorization` header of the request.
For example, if your Public ID is `public_test_123456324234234` and your Private Key is `private_test_9u2orjsd02lk3)i03423`,
then the field's value is the Base64 encoding of `public_test_123456324234234:private_test_9u2orjsd02lk3)i03423`.
Then the Authorization header field will appear as:
```http theme={null}
Authorization: Basic cHVibGljX3Rlc3RfMTIzNDU2MzI0MjM0MjM0OnByaXZhdGVfdGVzdF85dTJvcmpzZDAybGszKWkwMzQyMwo=
```
```bash cURL theme={null}
# The following Curl examples are equivalent.
# `-u` is the shorthand for `--user`, and can be used to avoid manually encoding the credentials.
curl -u 'public_test_123456324234234':'private_test_9u2orj....sd02lk3)i03423' \
-X POST \
--data '{"org_connection_id":"ebea708d-c5fa-4294-9051-da48ef08c78a"}' \
https://api.connect.fastenhealth.com/v1/bridge/fhir/ehi-export
curl -H 'Authorization: Basic cHVibGljX3Rlc3RfMTIzNDU2MzI0MjM0MjM0OnByaXZhdGVfdGVzdF85dTJvcmpzZDAybGszKWkwMzQyMwo=' \
-X POST \
--data '{"org_connection_id":"ebea708d-c5fa-4294-9051-da48ef08c78a"}' \
https://api.connect.fastenhealth.com/v1/bridge/fhir/ehi-export
```
```go Go theme={null}
publicID := "public_test_123456324234234"
privateKey := "private_test_9u2orjsd02lk3)i03423"
// Concatenate the Public ID and Private Key with a colon
authString := publicID + ":" + privateKey
// Base64 encode the concatenated string
encodedAuth := base64.StdEncoding.EncodeToString([]byte(authString))
// Create the Authorization header value
authHeader := "Basic " + encodedAuth
// Example HTTP request
req, err := http.NewRequest("POST", "https://api.connect.fastenhealth.com/v1/bridge/....", nil)
if err != nil {
fmt.Println("Error creating request:", err)
return
}
// Add the Authorization header
req.Header.Add("Authorization", authHeader)
client := &http.Client{}
resp, err := client.Do(req)
```
```javascript JavaScript/Node.js theme={null}
const https = require('https');
// Public ID and Private Key
const publicID = 'public_test_123456324234234';
const privateKey = 'private_test_9u2orjsd02lk3)i03423';
// Concatenate the Public ID and Private Key with a colon
const authString = `${publicID}:${privateKey}`;
// Base64 encode the concatenated string
const encodedAuth = Buffer.from(authString).toString('base64');
// Create the Authorization header value
const authHeader = `Basic ${encodedAuth}`;
// Example HTTP request options
const options = {
hostname: 'api.connect.fastenhealth.com',
port: 443,
path: '/v1/bridge/....',
method: 'POST',
headers: {
'Authorization': authHeader,
'Content-Type': 'application/json',
},
};
// Send the HTTP request
const req = https.request(options, (res) => {
console.log(`Status Code: ${res.statusCode}`);
});
req.end();
```
```python Python theme={null}
import requests
from requests.auth import HTTPBasicAuth
# Public ID and Private Key
public_id = "public_test_123456324234234"
private_key = "private_test_9u2orjsd02lk3)i03423"
# API endpoint
url = "https://api.connect.fastenhealth.com/v1/bridge/...."
# Make the POST request with Basic Authentication
response = requests.post(url, auth=HTTPBasicAuth(public_id, private_key))
```
```java Java theme={null}
String publicId = "public_test_123456324234234";
String privateKey = "private_test_9u2orjsd02lk3)i03423";
String endpoint = "https://api.connect.fastenhealth.com/v1/bridge/...";
// Concatenate Public ID and Private Key with a colon
String authString = publicId + ":" + privateKey;
// Base64 encode the concatenated string
String encodedAuth = Base64.getEncoder().encodeToString(authString.getBytes());
// Create the Authorization header value
String authHeader = "Basic " + encodedAuth;
// Create the HTTP connection
URL url = new URL(endpoint);
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Authorization", authHeader);
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
os.flush();
```
### Curl Example
# Bulk Catalog Export
Source: https://docs.connect.fastenhealth.com/api-reference/catalog/export
GET /bridge/catalog/export
Retrieve download links for the entire Fasten Connect catalog in one request.
Call this endpoint with your bridge API credentials (HTTP Basic auth using the `public_id` and `private_key`) whenever you need to hydrate an offline cache of our catalog.
Instead of iterating through the `/bridge/catalog` lookup endpoint, this API returns pre-signed URLs for JSON files that contain the entire public catalog:
* `brands.json` – Logos, names, TEFCA directory metadata, and other display properties for each brand.
* `portals.json` – Portal definitions, including login methods and the brands they belong to.
* `endpoints.json` – Technical endpoint configuration, such as FHIR base URLs, TEFCA IAS capability flags, and supported auth flows.
The download URLs expire after 60 minutes. Begin downloading the files immediately after requesting them.
This API is rate limited and the brand, portal and endpoint data structure is subject to change without notice.
**Please contact [support@fastenhealth.com](mailto:support@fastenhealth.com) before use.**
```json theme={null}
{
"brands.json": "https://fasten-connect-cdn-prod-1234/catalog/2024-06-28/brands.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=60&...",
"portals.json": "https://fasten-connect-cdn-prod-1234/catalog/2024-06-28/portals.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=60&...",
"endpoints.json": "https://fasten-connect-cdn-prod-1234/catalog/2024-06-28/endpoints.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=60&..."
}
```
# Get Catalog Entry
Source: https://docs.connect.fastenhealth.com/api-reference/catalog/get
GET /bridge/catalog
Get branding & metadata information associated with healthcare institutions supported by Fasten Connect.
`brand_id` OR `portal_id` is required.
This is used to display branding information in the Stitch.js popup widget.
This API not required, unless you are building a custom widget.
**Do not call this endpoint live on every request.**
Fasten may occasionally merge or deprecate IDs when the source EHR data changes or deletes records. To avoid broken references and improve performance:
- Cache the results returned by this endpoint.
- To check for updates, use the `org_connection_id` to call the [status endpoint](/api-reference/organization_connection/get) and retrieve the current `brand_id` and `portal_id`.
- Then, use those values to query the catalog GET endpoint and update your cached results accordingly.
Following this pattern ensures you always have the latest data without risking failures from deprecated IDs.
TEFCA If `tefca_directory_id` and `brand_id` are available, you should retrieve both. `tefca_directory_id` will provide an accurate name for the Healthcare Provider, while the `brand_id` can be used for logos and other branding information. However, if you can only retrieve one, prioritize `tefca_directory_id`.
TEFCA Directory IDs are subject to change by the TEFCA governing body and may be deprecated without notice. TEFCA Directory IDs are only cached for 2 weeks, after which they are removed from the catalog.
# Brand Logo Image
Source: https://docs.connect.fastenhealth.com/api-reference/catalog/logo
This endpoint allows you to retrieve the logo image of a healthcare institution.
```
https://cdn.fastenhealth.com/logos/sources/{{brand_id}}.png
```
Replace `{{brand_id}}` with the `brand_id` you received via your Redirect URL query parameters or from the `catalog/search` response.
# Search Catalog Brands
Source: https://docs.connect.fastenhealth.com/api-reference/catalog/search
POST /bridge/catalog/search
Search for healthcare institutions supported by Fasten Connect.
This is used to display branding information in the Stitch.js popup widget.
This API not required, unless you are building a custom widget.
This API is rate limited and is subject to change. **Please contact support@fastenhealth.com before use.**
# Bulk Records Request
Source: https://docs.connect.fastenhealth.com/api-reference/ehi_export/create
POST /bridge/fhir/ehi-export
This endpoint is idempotent. If a request with the same `org_connection_id` has already been registered, it will return the existing request.
This endpoint will register an bulk medical record export request with the Fasten Connect API for the provided `org_connection_id` (Patient id)
This functionality is similar in design to the HL7 [EHI Export](https://build.fhir.org/ig/argonautproject/ehi-api/ehi-export.html) specification.
However it is designed to be a unified API for all EHRs, as many EHRs do not support the HL7 EHI Export specification.
This endpoint requires an API public id & private key for authentication. Do not expose these keys in the browser.
This task will run asynchronously and may take some time to complete.
You can check the status of the task using the [Get Request Status](/api-reference/ehi_export/get) endpoint.
On completion a webhook will be sent to your `webhook_url` with metadata about the task, and a `download_link` to download the results.
# Download Bulk Records
Source: https://docs.connect.fastenhealth.com/api-reference/ehi_export/download
GET /bridge/fhir/ehi-export/{taskId}/download/{fileId}
When provided with a `taskId` and `fileId`, this endpoint will return a signed URL to download the file in the `Location` header.
Your http client should be able to follow the redirect and download the file.
This signed URL will expire after a short period of time, so you should download the file immediately.
If you are unable to do so, you can request a new signed URL by calling this endpoint again.
This endpoint requires an API public id & private key for authentication. Do not expose these keys in the browser.
# Get Request Status
Source: https://docs.connect.fastenhealth.com/api-reference/ehi_export/get
GET /bridge/fhir/ehi-export/{taskId}
Check the status of the EHI Export Task.
This is a polling endpoint intended for informational purposes only. It does not return the actual medical records or a `download_links` array.
Instead, the `download_links` will be sent asynchronously to a customer-defined [webhook](/webhooks/introduction).
We use [webhooks](/webhooks/introduction) to deliver the `download_links` because they are more reliable and scalable for background job completion.
Polling this endpoint repeatedly introduces unnecessary load and latency for your system and ours. Webhooks enable
instant delivery of results the moment they're ready.
**If your [webhook](/webhooks/introduction) is not configured, you will not be able to retrieve the exported EHI.**
This endpoint requires an API public id & private key for authentication. Do not expose these keys in the browser.
# Introduction
Source: https://docs.connect.fastenhealth.com/api-reference/introduction
Documentation for the Fasten Connect API
## Welcome
The Fasten Connect API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer).
Our API has predictable resource-oriented URLs, using JSON-encoded request & responses, and uses standard HTTP response codes, authentication, and verbs.
You can use the Fasten Connect API in test mode, which doesn’t affect your live data and only allows interactions with synthetic
patient data from healthcare institution sandboxes. The API key you use to authenticate the request determines whether
the request is live mode or test mode.
### Fasten Connect API Modes
The Fasten Connect API has two modes: `test` and `live`. Test mode is used for development and testing, while live mode is used for production.
Test mode secret keys have the prefix `private_test_` and live mode secret keys have the prefix `private_live_`.
| API Key Prefix | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `public_test_` | Test mode client-side key that uniquely identifies your app |
| `private_test_` | Test mode server-side key allows you to make authenticated requests. **Must be kept secret** |
| API Key Prefix | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `public_live_` | Live mode client-side key that uniquely identifies your app |
| `private_live_` | Live mode server-side key allows you to make authenticated requests. **Must be kept secret** |
# Get Organization
Source: https://docs.connect.fastenhealth.com/api-reference/organization/get
GET /bridge/org
Get information about your organization. This is used to display branding information in the Stitch.js popup widget.
# Get Organization Connection
Source: https://docs.connect.fastenhealth.com/api-reference/organization_connection/get
GET /bridge/org_connection/{orgConnectionId}
Check the status of an existing organization connection.
This endpoint requires an API public id & private key for authentication. Do not expose these keys in the browser.
# Initiate Connection
Source: https://docs.connect.fastenhealth.com/api-reference/registration/connect
GET /bridge/connect
This endpoint will generate a state value and redirect the user to their healthcare provider Patient Portal to authenticate with the healthcare provider's EHR.
On completion, Fasten Connect will redirect the user back to your redirect_uri with an `org_connection_id` and `endpoint_id` query parameter.
If an error occurred during the authentication process, Fasten Connect will redirect the user back with an `error` and `error_description` query parameter.
If you have configured more than one Redirect URL in the Fasten Connect Portal, you **MUST** include the `redirect_uri` query parameter in the request.
This is done automatically by the [Stitch SDK](stitch/v4/introduction) widget.
In `test` mode, you can use the following credentials to test the Fasten Stitch component:
| Source | Credentials / Sandbox Status | Link |
| ---------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| AdvancedMD | Username: Password: | |
| Aetna | Username: `VTETestUser01` Password: `FHIRdemo2020` | [test accounts](https://developerportal.aetna.com/sandbox_v2_test_member_logins_and_test_data_v2.1.xlsx) |
| AllScripts | Username: Password: | |
| Anthem | Username: `HOSPatient` Password: `HOSPatient2023` | |
| AthenaHealth | Username: `phrtest_preview@mailinator.com` Password: `Password1` | [test accounts](https://docs.athenahealth.com/api/guides/onboarding-overview) |
| CareEvolution | Username: `CEPatient` Password: `CEPatient2018` | [test accounts](https://fhir.careevolution.com/TestPatientAccounts.html) |
| Cerner | Username: `nancysmart` Password: `Cerner01` | [test accounts](https://docs.google.com/document/d/10RnVyF1etl_17pyCyK96tyhUWRbrTyEcqpwzW-Z-Ybs/edit) |
| Cigna | Username: `syntheticuser05` Password: `5ynthU5er5` | [test accounts](https://developer.cigna.com/service-apis/patient-access/sandbox#How-to-Use-the-Sandbox-Sandbox-Test-Users) |
| DynamicHealthIT | Username: Password: | |
| eClinicalWorks/Healow | Username: `AdultFemaleFHIR` Password: `e@CWFHIR1` | [test accounts](https://connect4.healow.com/apps/jsp/dev/r4/fhirClinicalDocumentation.jsp#SandboxTestingGuidelines) |
| Epic | Username: `fhircamila` Password: `epicepic1` | [test accounts](https://fhir.epic.com/Documentation?docId=testpatients) |
| Flatiron/OncoEMR | Username: Password: | |
| HealthIT | Username: `demouser` Password: `Demouser1!` | [test accounts](https://fhirsandbox.healthit.gov/secure/r4/view/userlogin.html) |
| Humana | Username: `HUser00001` Password: `PW00001!` | |
| Kaiser | Username: `Pvaluser1` Password: `V@lidation1` | |
| Logica | Username: Password: | |
| MaximEyes | Username: Password: | |
| Medhost | Username: Password: | |
| Medicare | Username: `BBUser00000` Password: `PW00000!` | [test accounts](https://bluebutton.cms.gov/developers/#developer-guidelines) |
| Meditech | Username: Password: | |
| Netsmart | Username: Password: | |
| NextGen | Username: `patientapitest` Password: `Password1!` | [test accounts](https://www.nextgen.com/-/media/files/api/nge-patient-api-auth-guide.pdf) |
| PracticeFusion/PatientFusion | Username: Password: | |
| VA Health | Provider: ID.me Username: `va.api.user+101-2024@gmail.com` Password: `Password12345!!!` | [test accounts](https://developer.va.gov/explore/api/patient-health/test-users/3617/7058f75892b845dbbd3f371703cc066f398c336a87bb51d73128f1bac24e3105) |
# Reconnect existing Connection
Source: https://docs.connect.fastenhealth.com/api-reference/registration/reconnect
GET /bridge/reconnect
This endpoint is used to reconnect an existing patient authorization with their healthcare provider's Patient Portal.
It generates a state value and redirects the user to the Patient Portal for re-authentication with the provider's EHR system.
This endpoint is only required if the existing connection id has expired or been revoked.
Upon successful completion, Fasten Connect will redirect the user back to the specified `redirect_uri` with the `org_connection_id` and `endpoint_id` query parameters.
If an error occurs during the re-authentication process, the user will be redirected back with `error` and `error_description` query parameters providing details about the failure.
If multiple Redirect URLs are configured in the Fasten Connect Portal, you **MUST** include the `redirect_uri` query parameter in the request. This is automatically handled by the [Stitch SDK](stitch/v4/introduction) widget.
TEFCA This endpoint CANNOT be used for TEFCA connections. TEFCA connections must be reconnected via the Stitch.js widget.
In `test` mode, you can use the following credentials to test the Fasten Stitch component:
| Source | Credentials / Sandbox Status | Link |
| ---------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| AdvancedMD | Username: Password: | |
| Aetna | Username: `VTETestUser01` Password: `FHIRdemo2020` | [test accounts](https://developerportal.aetna.com/sandbox_v2_test_member_logins_and_test_data_v2.1.xlsx) |
| AllScripts | Username: Password: | |
| Anthem | Username: `HOSPatient` Password: `HOSPatient2023` | |
| AthenaHealth | Username: `phrtest_preview@mailinator.com` Password: `Password1` | [test accounts](https://docs.athenahealth.com/api/guides/onboarding-overview) |
| CareEvolution | Username: `CEPatient` Password: `CEPatient2018` | [test accounts](https://fhir.careevolution.com/TestPatientAccounts.html) |
| Cerner | Username: `nancysmart` Password: `Cerner01` | [test accounts](https://docs.google.com/document/d/10RnVyF1etl_17pyCyK96tyhUWRbrTyEcqpwzW-Z-Ybs/edit) |
| Cigna | Username: `syntheticuser05` Password: `5ynthU5er5` | [test accounts](https://developer.cigna.com/service-apis/patient-access/sandbox#How-to-Use-the-Sandbox-Sandbox-Test-Users) |
| DynamicHealthIT | Username: Password: | |
| eClinicalWorks/Healow | Username: `AdultFemaleFHIR` Password: `e@CWFHIR1` | [test accounts](https://connect4.healow.com/apps/jsp/dev/r4/fhirClinicalDocumentation.jsp#SandboxTestingGuidelines) |
| Epic | Username: `fhircamila` Password: `epicepic1` | [test accounts](https://fhir.epic.com/Documentation?docId=testpatients) |
| Flatiron/OncoEMR | Username: Password: | |
| HealthIT | Username: `demouser` Password: `Demouser1!` | [test accounts](https://fhirsandbox.healthit.gov/secure/r4/view/userlogin.html) |
| Humana | Username: `HUser00001` Password: `PW00001!` | |
| Kaiser | Username: `Pvaluser1` Password: `V@lidation1` | |
| Logica | Username: Password: | |
| MaximEyes | Username: Password: | |
| Medhost | Username: Password: | |
| Medicare | Username: `BBUser00000` Password: `PW00000!` | [test accounts](https://bluebutton.cms.gov/developers/#developer-guidelines) |
| Meditech | Username: Password: | |
| Netsmart | Username: Password: | |
| NextGen | Username: `patientapitest` Password: `Password1!` | [test accounts](https://www.nextgen.com/-/media/files/api/nge-patient-api-auth-guide.pdf) |
| PracticeFusion/PatientFusion | Username: Password: | |
| VA Health | Provider: ID.me Username: `va.api.user+101-2024@gmail.com` Password: `Password12345!!!` | [test accounts](https://developer.va.gov/explore/api/patient-health/test-users/3617/7058f75892b845dbbd3f371703cc066f398c336a87bb51d73128f1bac24e3105) |
# Reset Synthetic Patient
Source: https://docs.connect.fastenhealth.com/api-reference/revoke/tefca_revoke
POST /bridge/vault_connection/revoke
Run this command to reset a TEFCA synthetic test patient's connections.
TEFCA This helper endpoint is only available while using `test` API credentials and is designed for clearing your TEFCA IAS sandbox before running another end-to-end scenario.
Authenticate with HTTP Basic auth using your organization public id and private key that are configured for **Test API Mode**. Requests made with live credentials will be rejected.
The request body **must** include an `email` value for one of the test synthetic patients documented in the [TEFCA IAS Developer Guide](/guides/tefca-ias#example-test-patients). All current connections for that synthetic patient are revoked so you can start a fresh flow.
# Support Request
Source: https://docs.connect.fastenhealth.com/api-reference/support/request
POST /support/request
File a support ticket with the Fasten team using our API.
This endpoint is in BETA and is not recommended for production use.
We reserve the right to remove this endpoint at any time.
This API is rate limited and is subject to change. **Please contact support@fastenhealth.com before use.**
# Changelog
Source: https://docs.connect.fastenhealth.com/changelog
Learn about the latest updates to the Fasten Connect service.
### Added
* Portal: Domain migrated from `portal.connect.fastenhealth.com` to `portal.fastenhealth.com`. We recommend updating any bookmarks & password managers to use the new domain.
* Portal: Portal UI has been completely updated to improve usability and accessibility. The new design includes a modern look and feel, improved navigation, and better support for mobile devices.
* Portal: Developer Portal now supports multiple organizations per account. This allows developers to manage multiple projects or clients from a single account.
* Portal: Added support for 2FA (Two-Factor Authentication) and other security enhancements.
### Added
* Docs: Expanded the test-data guide with Fasten's official FooClinic sandbox, including credentials, resource counts, and persona summaries for 16 synthetic patients. The guide also references external FHIR, clinical research, CCDA, and IPS datasets for broader pipeline testing.
### Added
* Stitch: Added an optional `email` attribute to the v4 Stitch SDKs. Customers can use it to prepopulate the patient's email address in TEFCA mode and support request/health system request forms.
### Added
* Docs/TEFCA: Clarified that TEFCA IAS mode requires cookies and that `localhost`, private browsing, or incognito testing can trigger browser cookie restrictions.
### Added
* Catalog/API: Added support for Medent, Medplum sandbox testing, and NextGen Office.
### Added
* TEFCA: Identity verification and TEFCA demographic matching now include historical patient addresses when available, improving matching for patients who have moved or previously received care at another address.
### Added
* TEFCA/Catalog: TEFCA record locator results now use Network Directory entries to resolve facilities to the correct catalog brand, portal, and endpoint metadata. This improves consistency for `tefca_directory_id` values and downstream webhook/catalog lookups.
### Added
* Identity/API: Added support for customer-managed identity verification flows, including OpenID Connect discovery, JWKS, pushed authorization requests and consent decisions.
* Identity/Stitch: Bring Your Own CSP flows now launch the Fasten widget with `request_uri`, use a simplified scope and use a consent form design aligned with the embedded widget.
### Added
* Stitch/Docs: Added Beta documentation for the React SDK, including installation, basic usage, TEFCA mode, component props, event handling, refs, and styling guidance.
### Added
* API/TEFCA: Documented the new `fixtures.tefca_ccda` option for `POST /bridge/fhir/ehi-export`, which lets API-mode TEFCA exports return a specific synthetic CCDA response during testing. Supported fixture values are `myra-jones.xml` and `lennie-connell.xml`.
* Docs/Webhooks & Events/TEFCA: Updated the TEFCA IAS guide and `patient.ehi_export_failed` failure reason docs to explain that `fixtures` can be used as a workaround for the common `tefca_no_documents_found` error in `test` mode.
### Added
* Webhooks & Events/TEFCA: Added `tefca_no_documents_found` as a documented `failure_reason` for `patient.ehi_export_failed`. This error is only returned when TEFCA mode is enabled and indicates that the health system did not return any records for the individual. It is frequently seen in `test` mode, but is uncommon in `live` mode.
### Added
* Catalog/API: Added the `GET /bridge/catalog/export` endpoint so customers can download pre-signed URLs for JSON files covering every brand, portal, and endpoint when hydrating offline catalog caches.
### Added
* API/TEFCA: Documented the helper endpoint `POST /bridge/vault_connection/revoke`, detailing how to clear TEFCA IAS synthetic patient connections with test credentials before running another scenario.
### Added
* Stitch: v4 release of the Stitch.js widget is now available for use. This version includes a number of bug fixes and improvements.
* Stitch: React Native SDK is now available. This allows you to integrate Fasten Connect into your React Native applications, providing a seamless experience for mobile users.
### Added
* Stitch/Webhooks: Documented the `tefca_directory_id` field, which is included for TEFCA IAS connections. This identifier can be used to provide branding information about the health system selected by the patient.
### Added
* TEFCA/Docs: TEFCA IAS is now Generally Available (GA). See our [new guide](/guides/tefca-ias) explaining how we keep the IAS flow simple for developers.
* Stitch/Webhooks: Documented TEFCA-specific behavior for Stitch events, including when identifiers may be omitted while using TEFCA mode.
* Stitch/Webhooks: Added new `consent_expires_at` field which can be used to determine when a patient's consent will expire. Supported in both TEFCA and Catalog Search modes.
* Webhooks & Events: `patient.connection_success` and `patient.authorization_revoked` are no longer beta-only
* Stitch: Clarified the reconnect flow (`reconnect-org-connection-id` skips search, emits the reconnection identifiers)
### Added
* Docs: Added Display & Component Library guide with fhir-react and fhirpath.js options for rendering FHIR data.
### Added
* Portal: When registering, domains are now claimed by the first organization created by an organization. Other developers must be invited to the associated team before they can login to the developer Portal.
### Added
* Stitch: Patients can now search for their healthcare institution using a partial match, improving the search experience and making it easier to find institutions with incomplete or approximate names.
### Added
* Portal: Accounts now require a corporate domain. Email addresses from providers like Gmail, Yahoo, etc., are no longer supported.
### Added
* Added documentation for `Catalog Editor` tool that allows Fasten customers to submit corrections to the provider catalog.
### Added
* Webhooks & Events: customers can now subscribe to the `patient.request_health_system` and `patient.request_support` webhook events. These events are emitted when a patient requests a new health system to be added to the Fasten Connect catalog, or when they request support during the connection process.
* Webhooks & Events: added `scope_patient_missing` failure\_reason to the `patient.ehi_export_failed` event. This indicates that the patient did not consent to share a required scope during the Consent flow.
### Added
* Stitch: documentation updated to reference the `widget.config_error` event. This event is emitted when the Stitch.js widget is misconfigured (e.g. invalid public key, missing required parameters, etc).
### Added
* API: documentation updated to reference the new `download_links` parameter. Returned by EHI-Export `patient.ehi_export_success` event.
### Deprecated
* API: the `download_link` provided by `patient.ehi_export_success` webhook event is now deprecated (will be removed in Jun, 2026), instead implementors should use the `download_links` array parameter when downloading patient records using the EHI-Export Download endpoint.
### Added
* Portal: Webhook simulator enhancements and schema alignment. The simulator now closely mirrors the actual webhook payload structure, making it easier to test and debug webhook integrations.
* Portal: Better email address validation error messages.
### Added
* Guides: Added Webhook simulator and debugging guide to help users test and troubleshoot webhook integrations.
### Added
* Stitch: Added instructions explaining how to customize the "Share Records" text on the Fasten Stitch button.
### Added
* API: Added dedicated `bridge/reconnect` endpoint to simplify the process of reconnecting (reauthorizing) an existing organization connection.
### Added
* Stitch: Added `search-query` property, which allows you to pre-populate the search box with a specific query. This can help users quickly find their health system without having to type it in manually.
* Stitch: Added `show-splash` property, which allows you to show or hide the splash screen that appears before the search popup. This can help build trust with users by displaying your own branding and introducing the Fasten Connect service.
### Added
* API: Added a large number of sanitized error types. This will help implementors to better understand why a request or data collection failed, and take appropriate action. Errors that cannot be adequately sanitized will return a generic 500 error code with no meaningful message.
### Added
* API: Org Connection Status endpoint will now return `scope` field, which indicates the resource types that were consented by the patient. This feature is currently in beta.
### Added
* Stitch: Added visible error details (type and description) when connection fails. Patients can now easily understand why the connection failed and submit a support request if needed.
### Added
* Portal: Added the ability to invite other administrators when creating a new organization.
* Webhooks: Added support for `patient.authorization_revoked` webhook event.
### Added
* Portal: Added information about current failure count to the webhook endpoint details page. This will help users understand the current status of their webhook endpoints and take necessary actions if needed.
### Added
* Catalog: Added the Department of Veterans Affairs (VA) to the catalog, allowing users to connect to their VA health records.
* Webhooks & Events: Improvements to ensure that webhook events are delivered even in cases where workers fail due to timeouts or memory issues.
### Added
* Stitch: Added `results.total` field to optional `search.query` event so customers can determine the total number of results returned by the search query.
### Added
* Webhooks & Events: You can now customize which webhook event types are subscribed to when creating or editing a webhook. Optional events can be selected or deselected freely, while required events remain enforced and cannot be removed.
* Webhooks & Events: The webhook editor UI has been improved. The **Update** button will only enable when changes are detected to the endpoint URL, webhook status, or selected event types.
### Added
* Catalog: Search enhancements, which should result in more accurate search results.
### Added
* Stitch: Added support for `event-types` query parameter in the Stitch.js widget. This allows you to opt-in to receive specific events in the `eventBus` event data, such as `search.query`
### Added
* Portal: When creating new credentials or webhooks, a notification email will be sent to all email addresses associated with the organization.
* Catalog: Anthem sandbox is now available for testing purposes.
* Webhooks & Events: Fixed an issue where Anthem EHR data collection would fail with an SSL/TLS error.
### Added
* Webhooks: Added a `stats` key to the `patient.ehi_export_success` webhook event payload.
### Added
* Stitch v1/v3: Fixed issue with Kaiser Permanente where the popup window will close immediately after opening, preventing the user from completing the authentication process.
* API: Fixed an issue in `redirect` mode, when using a [mobile deep link](https://en.wikipedia.org/wiki/Mobile_deep_linking), Kaiser & Humana would fail to return back to the application after authentication.
* API: Performance enhancement for health systems using Cerner (which should result in a 4x improvement in data collection & webhook delivery time).
### Added
* Stitch v3: Clarify that `widget.complete` event should be used in most cases, rather than `patient.connection_success`
### Added
* Webhooks: Added support for `patient.connection_success` webhook event.
### Added
* Quickstart: details for parsing the `eventBus` event data (using `JSON.parse()`) in the Stitch v3 example.
### Added
* Stitch v3: Fixed a bug where some connection failures incorrectly returned an `unknown_error_during_connect` error message.
* Quickstart: Stitch v3 is now the recommended version for integrating Fasten Connect into your application.
### Added
* Catalog: Added new aliases and metadata for healthcare institutions & health systems using AllScripts & Epic
### Added
* Stitch v3: All CSS styles are now namespaced with a `fhtw-` prefix. This means that any CSS styles provided by Fasten will not affect other elements on your page.
* Stitch v3: Bug: `connection_status` will always be present in the `widget.complete` event data.
* Stitch v3: Bug: `reconnect_org_connection_id` was not working correctly. This has been fixed.
### Added
* Webhooks: Added support for a `failure_reason` in the event payload.
### Added
* API: Added support for multiple `redirect_uris` in the Developer Portal. If you decide to provide multiple `redirect-uris`, you **MUST** populate the `redirect-uri` query string parameter when calling the [/connect](/api-reference/registration/connect) API endpoint..
### Added
* Catalog, API: updated catalog search engine to boost exact matches (on name and & aliases). This will increase search accuracy.
### Added
* API: fixed catalog search pagination. `searchAfter` no longer needs to be converted to string array. `sort` values can be passed to the API as-is (in mixed array of numbers and strings).
* API: adding status badges to show the status of various EHR sandbox accounts we provide for testing purposes, in `test` mode.
* Docs: Updated documentation to include a status badge for the sandbox accounts.
### Added
* Stitch: documentation related to "popup-timeout" parameter.
* Stitch: Fixed issue where duplicate events generated when multiple Stitch instances are used on the same page.
* API: Fixed issue where warnings emails were not correctly sent when a webhook is consistently failing, and will be disabled.
### Added
* API: documentation updated to reference the new `request_id` parameter sent to the Redirect URL. Provides a correlation ID that should be sent with ticket requests to the Fasten Connect support team.
* API: Added `support/request` endpoint to create a support ticket via the API.
* "Webhooks & Events": Added new `failure_reason` parameter sent with failed webhook events. Provides a sanitized reason for why the ehi-export operation failed, can be used for filtering/notifying patient to reauthenticate.
### Added
* Stitch: v3 release of the Stitch.js widget is now available for use. This version includes a number of bug fixes and improvements.
### Added
* Portal: Added some flexibility in the login system, allowing for clock skew between the client and server.
### Added
* API: Introduced ID Verification Provider - [CLEAR](https://www.clearme.com/)
### Added
* Catalog: NPI Numbers are now included in the `GET /v1/bridge/catalog` response.
### Added
* Portal: Added a note field for API credentials, helping users to identify the purpose of each credential.
### Added
* API: Automatically disable webhooks that are misbehaved (e.g. 404 errors). This is to prevent spam and abuse of the webhook system.
### Added
* API: documentation updated to reference the new `task_id` parameter. Used for both EHI-Export Status and Download endpoints.
### Deprecated
* API: the `org_connection_id` provided by webhook events is now deprecated (will be removed in Jan, 2024), instead implementors should use the `task_id` parameter when calling the EHI-Export Status and Download endpoints.
### Added
* Stitch: documentation related to redirect query string parameters on error. This includes the new `request_id` parameter.
### Added
* Stitch: Added the ability to provide an opaque `external_state` which is passed through to the Redirect URL on successful authentication.
### Added
* Webhooks & Events: Updated documentation
* Webhooks & Events: Added new Webhooks system, with support for retries, delivery logs & additional events.
* Webhooks & Events: Compliant with [standard-webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) spec
### Added
* Portal: Added the ability to delete API Credentials
### Added
* Stitch: Fixed `reconnect_org_connection_id` - when clicked, should automatically redirect patient to the Health System's login page.
### Added
* Stitch: Fixed swapped descriptions for `platform_type` and `connection_status`
* Quickstart: Clarified that Webhooks are `POST` requests
### Added
* Stitch: Using "Health System" term consistently in the UI
* Stitch: Added a warning message before redirecting to the Health System's login page
### Added
* Stitch: Platform Type (EHR system identifier) is now passed as a query parameter to the Redirect URL on successful authentication.
### Added
* Stitch: Added the ability to request missing Health Systems. Fixed Pagination of Brands
* Stitch: Added the ability to provide an opaque `external_id` which is passed through to the Redirect URL on successful authentication.
* Stitch: Added the ability to show and hide the Search popup programmatically using the `show()` and `hide()` methods.
### Added
* Catalog Search: Added the ability to search through all available healthcare institutions supported by Fasten Connect `POST /v1/bridge/catalog/search`
* Catalog Lookup: Added the ability to lookup a specific Fasten Connect brand or portal by it's id `GET /v1/bridge/catalog`
### Added
* Added the ability to authenticate patients via a popup using the Stitch.js SDK. `connect-mode="popup"`
# FAQs
Source: https://docs.connect.fastenhealth.com/faqs
Frequently Asked Questions
## Onboarding And Environment Setup
### What is the difference between test mode and live mode?
Test mode only connects to sandbox environments and synthetic or vendor-provided test data.
Live mode uses live credentials and production configuration. The Developer Portal toggle switches which mode's credentials,
webhooks, and logs you are viewing; it does not disable your account or permanently change your setup.
### Do test and live mode use separate API keys and webhooks?
Yes. Generate separate credentials and configure separate webhooks for test and live mode. Test credentials and test webhooks will not work in production (live mode).
### Can we reuse the same webhook URL in test and live mode?
No. Webhook URLs must be unique for your organization. Test and live webhooks have separate signing secrets, so use distinct URLs per environment.
## Support
### What identifiers should we include when requesting support?
Include any relevant identifiers so Fasten engineers can quickly locate the affected organization, connection, task, or request:
* `organization_id`: Your customer identifier. This helps us debug billing, payment, and webhook-related issues.
* `org_connection_id`: The patient consent or authorization identifier used to access a patient's records. This helps us debug patient consent and data collection errors.
* `task_id`: The worker task identifier generated when calling `/ehi-export`. This is only useful for data collection errors, especially when investigating a `patient.ehi_export_success` or `patient.ehi_export_failed` webhook event.
* `request_id`: The HTTP client correlation identifier, also known as a trace ID. This helps us debug specific API endpoint errors, including `4xx` or `5xx` responses, and can be useful for patient consent errors.
## Patient Connections
### Does a patient need to log in to every health system individually?
For portal-based SMART-on-FHIR connections, yes. The patient authorizes each health system or portal separately using that system's login flow.
For TEFCA mode, patients verify identity through a supported Credential Service Provider, such as CLEAR or ID.me, but TEFCA coverage depends on participating networks and source availability. Some workflows may still require portal login.
### How should we associate a Fasten connection with our user?
Pass a stable, server-generated user id, session id or equivalent reference as `external_id` when starting the flow.
### How do we know a connection succeeded?
Listen for the connection success client event and store the `org_connection_id`. This ID is the durable reference you will use for later export and status workflows.
We strongly recommend that you also register a webhook and listen for the `patient.connection_success` event as a backup or for auditing purposes.
### Why do some `patient.connection_success` records have `consent_expires_at` while others do not?
The `consent_expires_at` value is only available when the connected EHR can tell Fasten exactly when the patient's consent expires.
Historically, EHR vendors were not required to provide an introspection endpoint, so there was no reliable way to determine the exact consent expiration time. This became mandatory under HTI-2, which went into effect in January 2026. However, not every EHR has been certified against the updated requirements, and not every health system has upgraded to the latest version of its EHR software.
When an EHR cannot provide the expiration timestamp, Fasten omits `consent_expires_at`. In those cases, listen for the [`patient.authorization_revoked`](/webhooks/events#patient-authorization-revoked) webhook event.
## EHI Export
### Why does Fasten use JSONL files instead of FHIR Bundles?
Fasten supports exporting data in FHIR Bundle format, but we recommend using JSONL (also known as NDJSON) for several reasons:
1. **Reduced Redundancy**: FHIR Bundles often include redundant data structures. A Fasten-generated Bundle wrapper doesn’t provide any additional information compared to JSONL.
2. **Industry Standard for Large Exports**: JSONL is widely used in the HL7 community for large FHIR exports, including bulk/population EHI export endpoints.
3. **Streamlined Processing**: JSONL files are ideal for use with streaming JSON processors, which we recommend due to the variability in export sizes. Using a FHIR Bundle wrapper would make streaming processing either impossible or significantly more complex, depending on the programming language.
While we can provide FHIR Bundles if needed, JSONL is the default format because it's more efficient and better suited for most use cases.
### Where do we get failure details?
Use the `patient.ehi_export_failed` webhook. It contains the `failure_reason` and other context.
### How should I handle a `scope_patient_missing` error?
This error occurs when a patient deselects the **Demographics** permission during the consent process.
Without this permission, Fasten cannot consistently access the FHIR Patient resource, which contains the patient ID needed
to retrieve and filter other health records—even if the patient has approved access to those records.
Ask the patient to:
1. Restart the consent flow (by sending them to the [/api-reference/registration/reconnect](/api-reference/registration/reconnect) endpoint or your own reauthorization flow).
2. Make sure the **Demographics** permission is enabled during the consent process.
Patients may still choose which other record types to share, but Demographics must remain enabled for Fasten to retrieve their records successfully.
Because consent behavior varies among EHR systems, customers must currently handle this error and guide the patient through
reauthorization. Fasten is exploring ways to handle this scenario more automatically in the future.
### Do we need to poll the export status endpoint?
Prefer webhook-driven processing. Polling can be useful as a fallback, but webhooks are the primary path for completion and failure events.
## Webhooks
### Why did we receive duplicate webhooks?
Webhook systems are at-least-once delivery systems. Retries, network failures, and downstream acknowledgement timing can produce duplicate events with identical payload bodies or task IDs. Make webhook handlers idempotent.
### How many times are webhook events retried?
Fasten webhook delivery retries events with exponential backoff -- up to four retries over roughly the next 24 hours.
## Catalog Search And Provider Matching
### What should we do when a provider is missing from search?
Send support:
* Provider or facility name.
* Provider Website URL.
* Patient Portal URL (if available).
* Location, city, and state.
* Any DBA or alternate names.
### Can Fasten give an ETA for upstream EHR fixes?
Often no. EHR/vendor issues can be opaque and depend on that vendor's triage process. Fasten can file tickets, provide
evidence, and follow up, but source-side timelines are not always predictable.
## Sandbox And Test Data
### Is sandbox data representative of production?
Not always. Many EHR and payer sandboxes contain synthetic, incomplete, stale, huge, or malformed data. Some are heavily rate limited. Use sandbox data for integration mechanics, but validate product assumptions with live or more realistic datasets when possible. See our [Test Data Guide](/guides/test-data) for more details.
### Can the same sandbox patient exist across multiple providers or payers?
Usually no. Sandboxes are generally isolated by EHR or payer and are not coordinated with each other.
## TEFCA
### Does TEFCA replace portal login?
TEFCA can reduce reliance on individual portal logins, but it does not eliminate every portal-based workflow. Network coverage, QHIN behavior, identity proofing, and source participation all affect whether records are available through TEFCA.
### Why am I being asked to sign in to an Epic health system after completing TEFCA identity proofing?
Some Epic organizations currently require a patient to sign in to that organization's Epic portal as part of their TEFCA workflow. This is a limitation of Epic's current TEFCA implementation, not a failure of CLEAR or ID.me identity proofing.
Epic is developing federated identity support intended to let a patient sign in once and reuse that sign-in across Epic organizations (see [EpicID/MyChart Central](https://www.epic.com/software/mychart-central/)), but it is not yet available. Until then, patients may need the login credentials for each Epic organization that requests them.
### Why isn't an expected health system appearing or returning records in TEFCA?
* First, confirm that the specific health system participates in TEFCA by searching the [TEFCA Map](https://rce.sequoiaproject.org/tefca-map-search-offline/).
* Second, confirm that the patient's demographics match exactly with the data that has been verified by CLEAR or ID.me. See "Why do CLEAR and ID.me return different TEFCA results for the same person?" FAQ for more details.
If the organization participates & demographics are an exact match but a provider is still missing or returns no records, contact support with the health system name and the affected `request_id` or connection ID so we can investigate the request.
### Why do CLEAR and ID.me return different TEFCA results for the same person?
TEFCA uses the verified patient demographics—such as name, date of birth, and address—to match the patient against records held by participating health systems. Differences in the demographics provided or verified by CLEAR and ID.me can lead to different matches and results.
Compare the name, date of birth, address, and other identity details in each flow with the information on file at the health system. A mismatch can prevent records from being returned.
Learn more about demographics matching: [TEFCA IAS - Deep Dive into Patient Matching & RLS Responses](https://blog.fastenhealth.com/tefca-patient-matching-rls)
### Which identity providers are supported?
Fasten has supported CLEAR and ID.me for identity proofing. [BYO Identity](/identity-proofing/bring-your-own-identity) workflows may be available for eligible customers, but they require setup and confirmation.
### Why does TEFCA mode fail on localhost or in private browsing?
TEFCA mode requires cookies. When you host your app on `localhost`, browser security sandboxing can restrict cookies and prevent the TEFCA flow from completing. Similar cookie restrictions can occur in private browsing or incognito mode.
### Do TEFCA IAS authorizations expire, and how can I tell when a connection ends?
TEFCA IAS authorizations do not have a standard expiration period. Consequently, `consent_expires_at` is omitted for TEFCA connections; this is expected.
The connection remains authorized until the patient revokes consent or Fasten determines that the authorization is no longer valid. Enable the [`patient.authorization_revoked`](/webhooks/events#patient-authorization-revoked) webhook to receive notification when this occurs. This webhook is not enabled by default.
TEFCA requires IAS providers to support consent revocation but does not prescribe a fixed authorization lifetime. [TEFCA IAS Provider Requirements](https://rce.sequoiaproject.org/wp-content/uploads/2026/01/SOP-IAS-Provider-Requirements_v2.1_508.pdf)
This lack of guaranteed expiration is a known limitation of TEFCA, and is something they are actively working to address in future versions of the specification.
## Legal and Regulatory Compliance
### Is Fasten at risk of being shut down like other platforms that allow access to medical records for non-clinical use?
No, Fasten operates under a completely different legal framework compared to platforms like Particle Health, Health Gorilla and
Metriport which act as on-ramps to the national health information exchanges (HIEs). Here’s why Fasten is fundamentally different:
1. **Patient Access Rights**: Fasten leverages patient access to their own medical information, a right established under HIPAA and reinforced by the Cures Act Final Rule. This ensures patients can access and share their records electronically with any app or platform they choose.
2. **Patient Consent**: The process is built around patient consent. Patients log in via their provider’s patient portal and specify exactly which records they want to share.
3. **No HIE Dependency**: Unlike HIE on-ramp platforms, Fasten does not connect to HIEs or rely on their networks. HIEs operate as walled gardens requiring HIPAA compliance and specific clinical relationships, which has led to issues like the Particle Health - Epic lawsuit.
4. **Information Blocking Protections**: Blocking access to patient access APIs would constitute information blocking, which is strongly opposed by the ONC (now ASTP). These APIs are new (introduced in December 2022) and are designed to ensure patients have uninterrupted access to their data.
Fasten’s approach is fully aligned with patient rights and regulatory requirements, making it a secure and compliant platform for accessing medical records.
# Caching Strategy
Source: https://docs.connect.fastenhealth.com/guides/caching-strategy
Understand how Fasten Connect caches retrieved records and how the cache lifecycle works.
## Overview
Fasten Connect automatically caches the records it retrieves on your behalf. During the cache lifetime the platform serves
subsequent requests for the same `connection_id` directly from the cache, preventing redundant network calls to the source system
and improving response times for you and your users.
## Cache lifetime
* The default cache duration is 24 hours from the moment the record is first retrieved.
* While the cache entry is active, repeat requests for that record are fulfilled from the cached payload.
* Once the 24 hour window elapses, the system deletes the cached copy automatically. A follow-up request after that point
triggers a fresh retrieval and repopulates the cache for another 24 hour cycle.
## Operational notes
* You do not need to manage cache eviction; the platform handles expiration and cleanup.
* If you need to guarantee the most current data, wait for the existing cache to expire or request support for a
manual refresh.
* Monitor your integration for stale data if you are surfacing rapidly changing records to end users, and adjust
user-facing messaging accordingly.
# Contribute Catalog Updates
Source: https://docs.connect.fastenhealth.com/guides/catalog-editor
How Fasten customers can use the Fasten Toolbox to request provider catalog corrections.
Fasten provides the [Toolbox - Catalog Update](https://toolbox.fastenhealth.com/) as a lightweight portal where Fasten **customers** can explore the provider catalog and submit corrections. It is not a patient-facing application and should be used only by authorized customers.
## What You Can Do in the Toolbox
The Toolbox gives customers a self-service way to:
* Search the Fasten provider catalog by organization or health system name.
* Inspect the metadata attached to each provider record (e.g., aliases, website, logo, identifiers).
* Submit correction requests for spelling issues, missing names, incorrect URLs, outdated logos, missing NPI numbers, and other metadata gaps.
All submissions go through a manual review by the Fasten data operations team before any change becomes visible in the live catalog. This manual step ensures data accuracy and prevents unauthorized edits.
## Access and Intended Audience
* The Toolbox is limited to Fasten customers; do not share it with patients or use it in patient-facing workflows.
## Searching for Providers
1. Open [toolbox.fastenhealth.com](https://toolbox.fastenhealth.com/)
2. Use the global search bar to enter the provider, organization or health system name
3. Filter or refine terms if multiple results appear; searches match across official names, aliases, and known misspellings.
## Reading the Provider Entry
Each search result opens a detailed entry showing:
* Primary name and aliases.
* Official website and public contact URL.
* Associated brands, portals, or care locations.
* Current company logo and other branding assets.
* Identifiers such as NPI or CMS Certification Numbers (if available).
### Submitting Catalog Corrections
1. Choose the field(s) you want to update, such as:
* Names or aliases (e.g., fix capitalization or add a DBA name)
* Website URL or support portal link
* Company logo replacement (upload a clean PNG/SVG)
* NPI numbers or other identifiers
* Free-form notes for complex issues (e.g., mergers, portal deprecations)
2. Provide the corrected value plus any public references that help Fasten validate the change (official websites, press releases, provider directories, etc.).
3. Submit the request. You will **not** receive an email confirmation.
### Helpful Tips
* When updating logos, include a URL where the asset is publicly displayed so our team can confirm usage rights.
## Review and Approval Process
* Every correction is manually reviewed by a Fasten administrator before being applied to the production catalog.
* You may be contacted for clarification if supporting evidence is missing or ambiguous.
* Once approved, changes propagate to the Fasten Connect and Stitch experiences as part of our next catalog update (which occurs monthly).
## Getting Help
If you encounter issues searching the catalog, or receiving status updates on submissions, email [support@fastenhealth.com](mailto:support@fastenhealth.com) with the provider name and the date of your request.
# Display & Component Library
Source: https://docs.connect.fastenhealth.com/guides/display-component-library
Render and customize FHIR resources in your frontend with fhir-react or extract individual fields with fhirpath.js.
## Overview
If you need to preview Fasten Connect data in your product quickly, leverage existing component libraries instead of building
FHIR resource renderers from scratch. The **fhir-react** project gives you production-ready React components that accept raw JSON
resources, while **fhirpath.js** is a lightweight helper for pulling specific fields into custom UI. Most teams mix both: use
fhir-react for high-fidelity cards and fall back to fhirpath.js when you only need a data point or two.
## fhir-react in practice
[fhir-react](https://www.npmjs.com/package/fhir-react) is a React component library that renders FHIR resources across DSTU2, STU3,
and R4 (including CARIN Blue Button and DaVinci PDex) entirely on the client. It ships with Storybook-driven documentation so you can
preview every resource before embedding it in your app.
### Install & import
```bash theme={null}
npm install fhir-react
```
```tsx theme={null}
import { FhirResource, fhirVersions } from 'fhir-react';
import 'fhir-react/build/style.css';
import 'fhir-react/build/bootstrap-reboot.min.css';
function ResourceCard({ resource }) {
return (
);
}
```
### Icon strategy
* Let fhir-react provide defaults by omitting the `fhirIcons` prop.
* Pass a custom icon map (URL, ``, imported SVG module, or `false` to hide icons) for branded experiences.
```tsx theme={null}
const fhirIcons = {
Patient: require('assets/patient.svg'),
Encounter: ,
};
;
```
### Browse Storybook
deep links: [https://fastenhealth.github.io/fhir-react/](https://fastenhealth.github.io/fhir-react/)
Local run (required for Node ≥17):
```bash theme={null}
NODE_OPTIONS=--openssl-legacy-provider npm run storybook
```
Use Storybook to validate layouts, inspect props, and copy JSON fixtures before wiring them into your Fasten Connect integration.
### Suggested development flow
1. `npm install`
2. Run Storybook locally to explore components.
3. Import `FhirResource` (or other exports) and feed them resources returned by Fasten Connect.
4. Fine tune icons, profiles, and CSS overrides, then ship.
## When to reach for fhirpath.js
Sometimes you only need to show a field or two (e.g., `Patient.name[0].given[0]`) rather than the entire resource card. Use
[fhirpath.js](https://github.com/HL7/fhirpath.js) to evaluate FHIRPath expressions in the browser or server, then render the result
with your design system.
### Install
```bash theme={null}
npm install fhirpath
```
### Example: extract a display name
```ts theme={null}
import fhirpath from 'fhirpath';
export function getDisplayName(resource) {
const [name] = fhirpath.evaluate(resource, 'Patient.name.given[0] & " " & Patient.name.family');
return name ?? 'Unknown patient';
}
```
Use the extracted values in your components or pass them into analytics, search indices, or notification templates.
## Choosing the right tool
* Start with fhir-react when you want to stand up polished, data-rich cards with minimal effort.
* Layer fhirpath.js wherever you need to cherry-pick fields for bespoke UI, filters, or downstream systems.
* Combine both: render the full resource via fhir-react, but drive surrounding UI (breadcrumbs, headlines, CTAs) using values pulled with fhirpath.js.
By leaning on these libraries you minimize bespoke rendering code, accelerate delivery, and preserve fidelity across the numerous
FHIR profiles Fasten Connect makes available.
# Patient Consent & Data Collection
Source: https://docs.connect.fastenhealth.com/guides/patient-consent-data-collection
Understand how Fasten Connect guides patients through consent and how your systems collect the authorized data.
## Overview
Fasten Connect orchestrates a two-stage flow that begins when a patient authorizes access with Fasten Stitch and concludes when your systems retrieve their clinical data. Aligning your product and engineering teams around these stages keeps the experience compliant, transparent, and technically reliable.
1. **Patient Consent** — Patient-facing flows built with Fasten Stitch capture identity, grant authorization, and return the identifiers your backend needs to act on the consent.
2. **Data Collection** — Server-side jobs use the identifiers to request exports, monitor webhooks, and deliver the records to downstream systems while respecting retention policies.
## Stage 1: Patient Consent
### Your Role
* Introduce Fasten Stitch in your application where patients expect to manage their health data.
* Explain the benefits of sharing EHI and how their data will be used.
* Introduce Fasten as a trusted intermediary that simplifies access to multiple health systems.
* Confirm that the patient authenticated successfully with their health system.
* Persist the `org_connection_id` and related metadata emitted by Webhook or Stitch events for later API calls.
### Implementation steps
1. **Embed Stitch** — Add the [`fasten-stitch-element`](/stitch/v4/sdks/web-component/reference) to your application, supplying a public key that matches the deployment environment.
2. **Listen for events** — Parse the `widget.complete` event from the Stitch event bus and hand off the event payload to your backend over a secure channel.
* (Optional) Register a webhook endpoint so you can receive [`patient.connection_success` event](/webhooks/events#patient-connection-success-beta) notifications as a backup or for auditing.
3. **Store consent artifacts** — Persist the `org_connection_id`, `brand_id`, and other metadata alongside your patient record to build an auditable consent log.
Keep a short-lived cache of the most recent Stitch events to support patient support inquiries and replay protection.
### Success indicators
* Stitch reports `connection_status: authorized` for the selected health system.
* Your backend acknowledges receipt of the `org_connection_id` and ties it to the patient in your system of record.
* Consent timestamps and environment (test vs live) are recorded for audits.
## Stage 2: Data Collection
Once consent is recorded, shift to backend workflows that gather the authorized data and deliver it to the right destination.
### Kick off exports
* Use the [`/bridge/fhir/ehi-export`](/api-reference/ehi_export/create) endpoint with the stored `org_connection_id`.
* This API call must be made from a secure backend environment using your private key.
* Asynchronously handle the response, capturing the `task_id` for tracking.
### Monitor completion
* You will be automatically subscribed to [`patient.ehi_export_success`](/webhooks/events#patient-ehi_export_success) and related events at your registered webhook URL.
* Validate the `task_id` in incoming events against the job you launched and record progress updates for support visibility.
* Tasks will automatically time out after a reasonable period (Fasten will send a [`patient.ehi_export_failed`](/webhooks/events#patient-ehi_export_failed); implement retry logic for transient failures or delays.
### Retrieve records
* Retrieve the download link(s) from the webhook payload and stream the file(s) to your storage tier before the URLs expire
* Links are valid for 24 hours from the time of the webhook event.
* Import, convert or fan out the FHIR JSONL export into downstream formats (clinical data repository, data warehouse, analytics pipelines, or patient-facing portals).
* Ensure your systems can handle large files and variable resource counts. (eg. 30MB with 500 resources vs 3GB with 5,000 resources + Binary data).
* Use a Clinical Data Repository (CDR) that natively supports FHIR to simplify ingestion and querying.
* Open Source - [Medplum](https://www.medplum.com/), [HAPI](https://hapifhir.io/))
* [Azure Health Data Services](https://azure.microsoft.com/en-us/products/health-data-services)
* [AWS HealthLake](https://aws.amazon.com/healthlake/)
* [GCP Healthcare API](https://cloud.google.com/healthcare-api?hl=en)
* Apply retention policies: exports expire in Fasten storage after **24 hours**, so plan long-term retention in your own infrastructure.
## Putting it together
* **Orchestrate** both stages with a job tracker that links consent events, export requests, webhook updates, and downloads.
* **Inform patients** with status updates or notifications when collection finishes, reinforcing trust in the consent they granted.
* **Iterate** by reviewing failure logs from both stages to tune patient messaging, retry logic, and webhook reliability testing.
# TEFCA IAS Developer Guide
Source: https://docs.connect.fastenhealth.com/guides/tefca-ias
Learn about TEFCA IAS mode, its flow, and how to test with example patients.
There are additional fees involved with TEFCA IAS in `live` mode. Please contact [support@fastenhealth.com](mailto:support@fastenhealth.com) or your [Account Representative](https://calendly.com/jason-kulatunga/30min) for more information
## What is TEFCA IAS?
TEFCA (Trusted Exchange Framework and Common Agreement) is a framework designed to enable the secure and seamless exchange
of health information across the United States. The **Individual Access Services (IAS)** mode under TEFCA allows patients
to access their own health information electronically and share it with third-party applications or services.
Fasten Health supports a number of different mechanisms for retrieving medical records on behalf of patients, including TEFCA IAS.
Here's a short example of what the Fasten Connect widget looks like in TEFCA IAS mode:
***
## General Flow for Developers
From a developer’s perspective, here’s what’s happening under the hood when records flow through Fasten:
1. **QHIN Integration**
Fasten connects with a Qualified Health Information Network (QHIN). QHINs are essentially the access points to the TEFCA
framework. They provide the network APIs and routing needed to reach records across participating health systems.
2. **Identity Verification via CSPs**
To ensure patients are who they say they are, Fasten relies on Credential Service Providers (CSPs) certified by the Kantara
Initiative. These vendors verify patient identity using government ID + facial match and return an OpenID Connect Token
containing verified attributes (e.g., name, DOB).
3. **Secure Data Requests**
When Fasten queries the QHIN for records, it attaches the patient’s OpenID Connect Token. The QHIN
(and any downstream nodes) validate the token using the public key published by the CSP. This ensures requests are
tied to a verified patient identity and trusted by the network.
4. **Record Retrieval**
Once validated, Fasten can retrieve longitudinal health records from the appropriate source system through the QHIN,
normalize them, and make them available via our unified API.
Why it matters:
For developers, none of this extra wiring is something you need to implement. Fasten handles the QHIN partnerships,
identity assurance, token validation, and data normalization so your integration stays simple: a single API call to us.
***
## Enable Tefca Mode
If you've already followed our [Quickstart Guide](https://docs.connect.fastenhealth.com/quickstart), all you need to do is
set the `tefca-mode` attribute to `true` on the `` tag.
```html theme={null}
```
Cookies are required when using TEFCA IAS mode. If you are evaluating TEFCA mode while hosting your app on `localhost`, browser security sandboxing can restrict cookies and cause the flow to fail. Similar cookie restrictions can occur when testing in private browsing or incognito mode.
Yes, it's that simple!
There are additional fees involved with TEFCA IAS in `live` mode.
Please contact [support@fastenhealth.com](mailto:support@fastenhealth.com) or your [Account Representative](https://calendly.com/jason-kulatunga/30min) for more information
## Differences
* **Patient experience** – Catalog search and portal credential prompts are skipped. Patients are taken directly into a TEFCA IAS identity-proofing flow (CLEAR or ID.me), so adjust your in-product copy and support content to set that expectation before the widget launches.
* **Event/webhook payloads** – When TEFCA mode is on, `endpoint_id`, `portal_id`, and `brand_id` are often omitted from client events as well as `patient.connection_*` webhooks. Persist `tefca_directory_id` when it is returned so you still have a stable identifier for branding or analytics, and verify code paths that previously assumed the other catalog identifiers were always populated.
* **Scopes** – TEFCA connections always return a `scope` value of `patient/*.read`. If you surface granted scopes to users or use them for authorization logic, rely on this fixed scope string and remove assumptions about per-EHR variability.
* **No-records failure behavior** – TEFCA-enabled exports may fail with `failure_reason: tefca_no_documents_found` in the [`patient.ehi_export_failed`](/webhooks/events#patient-ehi_export_failed) webhook. This means the health system did not return any records for the individual. It is frequently seen in `test` mode, but is uncommon in `live` mode. If you are testing the API workflow, you can set `fixtures.tefca_ccda` on the EHI Export request to receive a known synthetic response instead of relying on the upstream test system to return data.
## Example Test Patients
To help developers test their integration with TEFCA IAS, we provide the following example test patients. These test patients
simulate real-world scenarios and can be used to validate your implementation.
| Name | Phone | Email | DOB | Gender | Address |
| ---------------------- | ------------ | ------------------------------------------------------------- | ---------- | ------ | --------------------------------------------------- |
| Allison Hackett | 608-555-1243 | [ahackett@gmail.com](mailto:ahackett@gmail.com) | 01/15/1987 | Female | 1325 Main St, Madison, WI, US 57303 |
| Damon Mychart | 608-211-3314 | [dmychart@gmail.com](mailto:dmychart@gmail.com) | 07/26/1979 | Male | 308 Oak St, Madison, WI, US 53711 |
| **Dog Beaker** | 410-707-2690 | [dogbeaker@aol.com](mailto:dogbeaker@aol.com) | 11/24/1985 | Male | 124 Lake Street, Vernon, CT, US 06066 |
| Barbara Testa | 831-600-3769 | [btesta@hotmail.com](mailto:btesta@hotmail.com) | 05/24/1947 | Female | 8855 Orchid Blvd, Reading, PA, US 19602 |
| Tracy CraneTest | 222-360-1564 | [tcranetest@gmail.com](mailto:tcranetest@gmail.com) | 12/26/1936 | Female | 458 Streich Street Lunenburg, MA, US 01462 |
| **Camila Maria Lopez** | 469-469-4321 | [knixontestemail@epic.com](mailto:knixontestemail@epic.com) | 09/12/1987 | Female | 3268 West Johnson St. Apt 117 Garland, TX, US 75043 |
| Derrick Lin | 785-785-4321 | [knixontestemail2@epic.com](mailto:knixontestemail2@epic.com) | 06/3/1973 | Male | 7324 Roosevelt Ave Indianapolis, IN, US 46201 |
| Homer J Simpson | 217-123-3608 | [hsimpson@gmail.com](mailto:hsimpson@gmail.com) | 02/9/1975 | Male | 742 Evergreen Terrace Madison, WI, US 53711 |
### Clear Test Patients
CLEAR's verification process in TEFCA mode uses the following patient identifiers to automatically match the test patients in the table above:
| Name | Phone | Email |
| ---------------------- | ------------ | ------------------------------------------------------------- |
| Allison Hackett | 608-555-1243 | [ahackett@gmail.com](mailto:ahackett@gmail.com) |
| Damon Mychart | 608-211-3314 | [dmychart@gmail.com](mailto:dmychart@gmail.com) |
| **Dog Beaker** | 410-707-2690 | [dogbeaker@aol.com](mailto:dogbeaker@aol.com) |
| Barbara Testa | 831-600-3769 | [btesta@hotmail.com](mailto:btesta@hotmail.com) |
| Tracy CraneTest | 222-360-1564 | [tcranetest@gmail.com](mailto:tcranetest@gmail.com) |
| **Camila Maria Lopez** | 469-469-4321 | [knixontestemail@epic.com](mailto:knixontestemail@epic.com) |
| Derrick Lin | 785-785-4321 | [knixontestemail2@epic.com](mailto:knixontestemail2@epic.com) |
| Homer J Simpson | 217-123-3608 | [hsimpson@gmail.com](mailto:hsimpson@gmail.com) |
[source](https://docs.clearme.com/docs/synthetic-test-patients)
### ID.me Test Patients
Most of the ID.me synthetic identities are not functional. ID.me is working to resolve this issue. Please use the CLEAR identities above to test in TEFCA mode.
ID.me verification process in TEFCA mode is based on a username and password. The following test users are available:
| Name | Email | Password |
| ---------------------- | ------------------------------------------------------------- | ---------- |
| Allison Hackett | [ahackett@gmail.com](mailto:ahackett@gmail.com) | IDme2026!! |
| Damon Mychart | [dmychart@me.com](mailto:dmychart@me.com) | IDme2026!! |
| **Dog Beaker** | [dogbeaker@aol.com](mailto:dogbeaker@aol.com) | IDme2026!! |
| Barbara Testa | [btesta@hotmail.com](mailto:btesta@hotmail.com) | IDme2026!! |
| Tracy CraneTest | [tcranetest@gmail.com](mailto:tcranetest@gmail.com) | IDme2026!! |
| **Camila Maria Lopez** | [knixontestemail@epic.com](mailto:knixontestemail@epic.com) | IDme2026!! |
| Derrick Lin | [knixontestemail2@epic.com](mailto:knixontestemail2@epic.com) | IDme2026!! |
| Homer J Simpson | [hsimpson@gmail.com](mailto:hsimpson@gmail.com) | IDme2026!! |
### How to Use Test Patients
1. Embed the Fasten Connect widget in your application with TEFCA IAS mode enabled.
2. Log in with the provided email address
3. When prompted to provide identity verification (using Clear or ID.me), use the corresponding phone number + email address (for CLEAR) or email address + password (for ID.me)
4. Follow the flow to authenticate, consent, and retrieve data.
### Use Fixtures for Deterministic Test Exports
When you are testing TEFCA IAS with the API workflow, the TEFCA environment will often return no documents for synthetic users. In that case, the EHI Export job may fail with `failure_reason: tefca_no_documents_found` even though your integration is working correctly.
To avoid that during testing, pass the `fixtures.tefca_ccda` option when calling [`POST /bridge/fhir/ehi-export`](/api-reference/ehi_export/create). This tells Fasten to return a specific synthetic CCDA payload for the export instead of depending on the TEFCA test network to return records.
This option is only available in `test` mode.
```json theme={null}
{
"org_connection_id": "xxxxx",
"fixtures": {
"tefca_ccda": "myra-jones.xml"
}
}
```
Available values for `fixtures.tefca_ccda`:
* `myra-jones.xml`
* `lennie-connell.xml`
* `myra-jones-v2.xml`
* `myra-jones-v7.xml`
* `bernice-maxwell.xml`
See the [TEFCA Test Fixtures](/guides/test-data#tefca-test-fixtures) section of the Test Data Sources guide for patient summaries, resource counts, source links, and unsupported-sample notes.
### Reset Synthetic Patients Between Runs
When you finish an end-to-end scenario, that synthetic patient now has active vault connections. Before running another test, clear those connections by calling the helper endpoint `POST /bridge/vault_connection/revoke`.
* Authenticate with HTTP Basic auth using your **test** mode public id/private key; live credentials are rejected.
* Pass the `email` of the synthetic patient you want to reset (see the table above).
* All vault connections for that patient are revoked so the next run starts from a clean slate.
```bash theme={null}
curl -X POST https://api.connect.fastenhealth.com/v1/bridge/vault_connection/revoke \
-u "public_test_xxxxxxxxxx:private_test_xxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"email": "dogbeaker@aol.com"
}'
```
***
If you encounter any issues or need further assistance, contact our support team at [support@fastenhealth.com](mailto:support@fastenhealth.com).
# Test Data Sources
Source: https://docs.connect.fastenhealth.com/guides/test-data
Most EHR-provided "sandbox" patients are little more than UI demos -- they rarely resemble the volume, structure, or messiness of production data.
Use Fasten's official FooClinic test server and curated external datasets to validate ingestion, normalization, and downstream analytics before you onboard live connections.
FooClinic provides predictable synthetic patient personas for end-to-end Fasten testing, while third-party datasets help you cover larger volumes, different formats, and messier clinical scenarios.
## Official FooClinic Test Data
FooClinic is Fasten's official sandbox test server. Use these synthetic patient personas to validate the Fasten Widget sign-in flow and downstream EHI export handling with predictable test data.
In the Fasten Widget, choose **FooClinic (Sandbox)** from the health system list.
Start the sandbox portal flow by clicking **Sign in**.
Sign in with one of the usernames and passwords in the table below.
Ages are calculated from fixture birth dates as of July 2026.
| Test Patient | Credentials | Resource Count | Persona Summary |
| :--------------------- | :------------------------------------------------------------------- | :------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anne Goodwin | Username: `annegoodwin@fooclinic.com` Password: `f00clinic` | 421 | 14-year-old female childhood asthma persona; includes care transition/relocation data, 45 DocumentReferences, 47 DiagnosticReports, 25 Immunizations, and 232 Observations. |
| Salina Mebrat Tesfay | Username: `salinatesfay@fooclinic.com` Password: `f00clinic` | 333 | 17-year-old female childhood obesity persona; includes 6 JSON DocumentReferences, 1 DX ImagingStudy, and 2 DiagnosticReports. |
| Sydney-Camryn Phar | Username: `sydneyphar@fooclinic.com` Password: `f00clinic` | 8 | 16-year-old female compact childhood obesity persona; includes 2 JSON DocumentReferences. |
| Aaron697 Reichert620 | Username: `aaronreichert@fooclinic.com` Password: `f00clinic` | 573 | 71-year-old male mCode oncology persona; includes 32 text DocumentReferences, 1 DX ImagingStudy, and 60 DiagnosticReports. |
| Alex454 Marvin195 | Username: `alexmarvin@fooclinic.com` Password: `f00clinic` | 212 | 83-year-old male mCode oncology persona; includes 18 text DocumentReferences and 22 DiagnosticReports. |
| Betsy Smith-Johnson | Username: `betsyjohnson@fooclinic.com` Password: `f00clinic` | 24 | 75-year-old female PACIO advance care planning persona; includes end-of-life preferences, Consent, Device, DocumentManifest and 17 Observations. |
| Earl Carrillo | Username: `earlcarrillo@fooclinic.com` Password: `f00clinic` | 3556 | 60-year-old male non-small cell lung cancer persona; high-volume oncology record with 3 Devices, 294 DiagnosticReports, 91 DocumentReferences, 2,755 Observations, and 277 Procedures. |
| John Doe | Username: `johndoe@fooclinic.com` Password: `f00clinic` | 11 | 71-year-old male compact diabetic baseline persona; includes Device, DiagnosticReport, Medication, MedicationStatement, Immunization, and core clinical history. |
| Marcella Schumm | Username: `marcellaschumm@fooclinic.com` Password: `f00clinic` | 531 | 38-year-old female complex chronic illness and pregnancy persona; includes 56 DocumentReferences, 79 DiagnosticReports, 153 Observations, and 141 Procedures. |
| Markus Ward | Username: `markusward@fooclinic.com` Password: `f00clinic` | 1919 | 53-year-old male congestive heart failure and cardiac rehabilitation persona; includes 2 Devices, 320 DocumentReferences, 399 DiagnosticReports, and 748 Observations. |
| Patricia Noelle | Username: `patricianoelle@fooclinic.com` Password: `f00clinic` | 19 | 71-year-old female compact MCC eCarePlan/asthma persona; includes CareTeam, ServiceRequest, QuestionnaireResponse, DiagnosticReport, and referral workflow data. |
| Season349 O'Connell601 | Username: `seasonoconnell@fooclinic.com` Password: `f00clinic` | 1387 | 102-year-old female Coherent persona; includes 2 ImagingStudies, 1 ECG Media resource, DICOM Binary, DNA CSV Binary sidecar, and patient-linked DocumentReferences. |
| Spencer Thompson | Username: `spencerthompson@fooclinic.com` Password: `f00clinic` | 284 | 12-year-old male acute myeloid leukemia persona; includes childhood leukemia care data, CarePlan/CareTeam records, Claims, Immunizations, 199 Observations, and Procedures. |
| William Sim | Username: `williamsim@fooclinic.com` Password: `f00clinic` | 10 | 13-year-old male pediatric oncology-style persona; compact record with radiology procedure history, Conditions, Encounters, Observation, and Procedures. |
| Wilma Nader | Username: `wilmanader@fooclinic.com` Password: `f00clinic` | 220 | 19-year-old female COVID-19 / Long COVID home-health persona; includes CarePlan/CareTeam records, Claims, Immunizations, Medication, 137 Observations, Procedures, and QuestionnaireResponse. |
| Aleta47 Ortiz186 | Username: `aletaortiz@fooclinic.com` Password: `f00clinic` | 305 | 112-year-old female Coherent persona; includes 1 DX ImagingStudy, 1 Device, DICOM Binary, DNA CSV Binary sidecar, and patient-linked DocumentReferences. |
Need a new synthetic test patient? Contact [support@fastenhealth.com](mailto:support@fastenhealth.com) with:
* Persona summary
* Required FHIR resource types
* Expected record size or volume
* Edge cases needed for your testing workflow
## TEFCA Test Fixtures
Fasten embeds these deterministic C-CDA fixtures for TEFCA API-mode testing. Pass a fixture name as `fixtures.tefca_ccda` when creating an EHI export in `test` mode through the [EHI Export request's fixtures option](/api-reference/ehi_export/create#body-fixtures).
Ages are calculated from fixture birth dates as of July 2026.
| Fixture | FHIR resources | Patient and persona / coverage |
| :-------------------- | :------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `myra-jones.xml` | 51 | Myra Jones, 79-year-old female. Older-adult pneumonia and asthma record with allergies, encounters, discharge medications, functional status, social history, and vital signs. |
| `myra-jones-v2.xml` | 26 | Myra Jones, 79-year-old female. Compact public Myra variant used to regression-test converter handling of optional or missing values. |
| `myra-jones-v7.xml` | 81 | Myra Jones, 79-year-old female. Larger public Myra variant with broader allergy, condition, diagnostic, medication, observation, procedure, and care-plan coverage. |
| `lennie-connell.xml` | 44 | Lennie Connell, 62-year-old male. Adult record covering acute pharyngitis, atrial fibrillation, flu-like illness, tobacco use, medications, plans, procedures, immunizations, and results. |
| `bernice-maxwell.xml` | 43 | Bernice Maxwell, 85-year-old female. EMERGE health-summary sample covering allergies, encounters, immunizations, medications, conditions, procedures, observations, and related persons. |
The three Myra fixtures intentionally represent the same patient demographics in different C-CDA documents. This gives integrations duplicate-patient coverage for comparing document variants without inventing a synthetic identity.
## External datasets
In addition to FooClinic, you can use curated external datasets to validate your ingestion, normalization, and downstream
analytics workflows. These datasets are useful when you need broader coverage than the FooClinic personas, such as bulk FHIR exports for population health analysis, research datasets, or format conversion fixtures.
### How to use synthetic patient data
Pick data that matches the workflow you want to mimic, such as FHIR Bulk exports, claims-heavy data, or pediatrics.
If necessary, convert the dataset to newline-delimited JSON. Fasten's `/ehi_export` endpoint provides FHIR resources in NDJSON format, with one resource per line.
Drop NDJSON files into the same object storage bucket that you store Fasten exports in, or POST bundles against your local test endpoint.
Run the exact conversions and validations you expect to run for real patients, including schema validation, de-identification, transformations, and downstream notifications.
Use Fasten's `/ehi_export` payloads when you are ready for end-to-end testing. No code changes should be required if your fixtures match the contract.
Keep the original archive of each dataset in version control or object storage so test runs are reproducible and easy to diff across releases.
Use these when you need broader coverage than the FooClinic personas, such as bulk FHIR exports, research datasets, or format conversion fixtures.
### FHIR and synthetic patient datasets
* [Synthea downloads](https://synthea.mitre.org/downloads) - Synthetic patient populations in several export formats.
* [Synthea project](https://synthetichealth.github.io/synthea/) - Generator and documentation for creating configurable synthetic patient records.
* [Standard Patient Health Record personas](https://build.fhir.org/ig/HL7/standard-patient-health-record-ig/branches/master/personas-index.html) - HL7 sample personas for repeatable patient scenarios.
* [SMART sample bulk FHIR datasets](https://github.com/smart-on-fhir/sample-bulk-fhir-datasets) - Bulk FHIR examples for validating NDJSON ingestion.
### Clinical research datasets
* [MIMIC-IV FHIR demo](https://physionet.org/content/mimic-iv-fhir-demo/2.0/) - Demo FHIR resources derived from MIMIC-IV.
* [MIMIC-III clinical database](https://physionet.org/content/mimiciii/1.4/) - De-identified critical care data for research workflows.
* [MIMIC FHIR downloads](https://mimic.mit.edu/fhir/downloads.html) - FHIR-formatted MIMIC datasets and related downloads.
* [Synthetic health data survey](https://www.mdpi.com/2079-9292/11/8/1199) - Reference material for synthetic EHR data generation and evaluation.
### FHIR examples and tutorials
* [HAPI FHIR transaction tutorial](https://github.com/hapifhir/fhir-tutorial/blob/master/Transactions/lesson.md) - Example transaction bundles for local FHIR testing.
### CCDA samples
* [Sample CCDAs](https://github.com/jmandel/sample_ccdas)
* [CCDA to FHIR samples](https://github.com/chunli866/CCDAtoFHIRSamples)
* [Microsoft FHIR Converter CCDA samples](https://github.com/microsoft/FHIR-Converter/tree/main/data/SampleData/Ccda)
### IPS samples
* [HL7 IPS example bundle](https://github.com/HL7/fhir-ips-ri/blob/main/examples/example_bundle/IPS-bundle-01.json)
# Test Patient Credentials
Source: https://docs.connect.fastenhealth.com/guides/test-patient-credentials
Use pre-configured sandbox logins to explore EHR portals in test mode and validate your Fasten Stitch experience.
## Overview
Fasten Connect provides a curated list of sandbox portal logins so you can authenticate against major EHRs as a test patient.
These credentials only work while your integration is running in `test` mode. They are ideal for logging into Epic, Cerner, AthenaHealth, and other health systems to validate OAuth flows,
tune UI messaging, and ensure Fasten Stitch renders the right prompts at each stage of the connection.
## Credential catalog
Each sandbox account mimics a patient record inside its respective vendor portal. Because they are controlled environments,
you might notice limited or unrealistic data. Use the table below to pick the health system, log in as the provided test patient,
and walk through the consent process end-to-end.
Fasten's official test server is FooClinic, which includes multiple synthetic patient personas for richer end-to-end testing. See the [Official FooClinic Test Data](/guides/test-data#official-fooclinic-test-data) section for available patients, credentials, resource counts, and persona summaries.
| Source | Credentials / Sandbox Status | Link |
| ---------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| AdvancedMD | Username: Password: | |
| Aetna | Username: `VTETestUser01` Password: `FHIRdemo2020` | [test accounts](https://developerportal.aetna.com/sandbox_v2_test_member_logins_and_test_data_v2.1.xlsx) |
| AllScripts | Username: Password: | |
| Anthem | Username: `HOSPatient` Password: `HOSPatient2023` | |
| AthenaHealth | Username: `phrtest_preview@mailinator.com` Password: `Password1` | [test accounts](https://docs.athenahealth.com/api/guides/onboarding-overview) |
| CareEvolution | Username: `CEPatient` Password: `CEPatient2018` | [test accounts](https://fhir.careevolution.com/TestPatientAccounts.html) |
| Cerner | Username: `nancysmart` Password: `Cerner01` | [test accounts](https://docs.google.com/document/d/10RnVyF1etl_17pyCyK96tyhUWRbrTyEcqpwzW-Z-Ybs/edit) |
| Cigna | Username: `syntheticuser05` Password: `5ynthU5er5` | [test accounts](https://developer.cigna.com/service-apis/patient-access/sandbox#How-to-Use-the-Sandbox-Sandbox-Test-Users) |
| DynamicHealthIT | Username: Password: | |
| eClinicalWorks/Healow | Username: `AdultFemaleFHIR` Password: `e@CWFHIR1` | [test accounts](https://connect4.healow.com/apps/jsp/dev/r4/fhirClinicalDocumentation.jsp#SandboxTestingGuidelines) |
| Epic | Username: `fhircamila` Password: `epicepic1` | [test accounts](https://fhir.epic.com/Documentation?docId=testpatients) |
| Flatiron/OncoEMR | Username: Password: | |
| HealthIT | Username: `demouser` Password: `Demouser1!` | [test accounts](https://fhirsandbox.healthit.gov/secure/r4/view/userlogin.html) |
| Humana | Username: `HUser00001` Password: `PW00001!` | |
| Kaiser | Username: `Pvaluser1` Password: `V@lidation1` | |
| Logica | Username: Password: | |
| MaximEyes | Username: Password: | |
| Medhost | Username: Password: | |
| Medicare | Username: `BBUser00000` Password: `PW00000!` | [test accounts](https://bluebutton.cms.gov/developers/#developer-guidelines) |
| Meditech | Username: Password: | |
| Netsmart | Username: Password: | |
| NextGen | Username: `patientapitest` Password: `Password1!` | [test accounts](https://www.nextgen.com/-/media/files/api/nge-patient-api-auth-guide.pdf) |
| PracticeFusion/PatientFusion | Username: Password: | |
| VA Health | Provider: ID.me Username: `va.api.user+101-2024@gmail.com` Password: `Password12345!!!` | [test accounts](https://developer.va.gov/explore/api/patient-health/test-users/3617/7058f75892b845dbbd3f371703cc066f398c336a87bb51d73128f1bac24e3105) |
## Data expectations & testing strategy
* Sandbox accounts **vary widely in both the quantity and quality of data they expose**. Some include full longitudinal histories
while others only show a handful of labs or medications.
* For UI testing or machine learning exercises, we strongly reccommend that you use the richer synthetic resources outlined in the
[Test Data guide](/guides/test-data).
# Webhook Debugging & Simulator
Source: https://docs.connect.fastenhealth.com/guides/webhook-debugging-simulator
Fasten Connect provides two tools to help developers test and debug webhook integrations: **Delivery Logs** and the **Webhook Simulator**.
Together, these make it easier to confirm that your endpoints are configured correctly and to troubleshoot issues quickly.
***
## 1. Webhook Delivery Logs
The **Delivery Logs** page shows a history of recent webhook events Fasten attempted to deliver to your endpoint.
Delivery logs are only available for the last 15 days.
Each log entry includes:
* **Event Type** (e.g. `patient.ehi_export_success`, `patient.ehi_export_failed`)
* **Request Payload** – the JSON we sent to your endpoint
* **Response** – the HTTP status code and body your server returned
* **Timestamp** – when the delivery attempt was made
### How to Use Delivery Logs
1. Navigate to **Developer** tabg in the Fasten Connect dashboard.
2. Find the "Delivery Logs" column in the Webhooks table and click **View Logs** for the webhook you want to inspect.
3. Click an event to expand the **Request** and **Response** details.
* Use the **Request** JSON to confirm the payload structure matches what your endpoint expects.
* Check the **Response** for HTTP status codes (e.g., `200 OK` means success; `403 Forbidden` or `500 Server Error` indicate problems on your side).
3. If your endpoint repeatedly fails, Fasten will automatically disable the webhook after multiple consecutive errors. A yellow banner will warn you before this happens.
### Common Debugging Scenarios
* **403 Forbidden** – Your endpoint is rejecting the request. Confirm that your server allows Fasten’s IPs and that you’re validating the **Signing Secret** correctly.
* **Timeouts** – Ensure your endpoint responds within a reasonable timeframe. Consider acknowledging the event quickly (e.g., `200 OK`) and handling long-running jobs asynchronously.
* **Invalid Payload Handling** – Verify your endpoint can parse the JSON and handle optional fields that may or may not be present.
***
## 2. Webhook Simulator
The **Webhook Simulator** allows you to generate test events on demand, without waiting for a real patient workflow. This is useful for local development and automated testing.
The Webhook Simulator is only available in `test` mode. You cannot simulate payloads in `live` mode.
### How to Use the Simulator
1. Navigate to **Developer** tabg in the Fasten Connect dashboard.
2. Find the "Delivery Logs" column in the Webhooks table and click **View Logs** for the webhook you want to simulate events with.
3. Click **Simulate Webhook**.
4. Select an **Event Type** from the dropdown (e.g., `Patient EHI Export Success`).
5. Review or edit the **Payload JSON**. Defaults are pre-filled with valid values, but you can change them to test edge cases (e.g., missing optional fields, large resource counts).
6. Click **Send Simulated Payload**.
* This will immediately POST the JSON to your registered webhook endpoint.
* The event will also appear in the **Delivery Logs**, just like real events. Events may take a few seconds to show up.
### Best Practices
* Use the simulator to test endpoint logic before going live.
* Test both **success** and **failure** event types to ensure your system handles retries and errors gracefully.
* Validate that your application parses required fields (like `download_links`) and ignores fields you don’t use.
***
## Summary
* **Delivery Logs** help you debug by showing exactly what Fasten sent and how your server responded.
* **Webhook Simulator** lets you test any event type instantly, with customizable payloads.
* Together, these tools ensure your webhook integration is reliable before moving into production.
***
If you encounter any issues or need further assistance, contact our support team at [support@fastenhealth.com](mailto:support@fastenhealth.com).
# Home
Source: https://docs.connect.fastenhealth.com/home
Welcome to the Fasten Connect Docs
## Explore
Here you'll find guides, resources, and references to build with Fasten Connect.
Learn about Fasten Connect's key concepts and how to get started
Explore our API Endpoints
Fasten Stitch.js, Fasten's client-side component, helps your users connect their accounts.
# Bring Your Own Identity
Source: https://docs.connect.fastenhealth.com/identity-proofing/bring-your-own-identity
Use your own AAL2 authentication and CSP identity-proofing flow with Fasten Connect and TEFCA IAS.
There are additional fees involved with TEFCA IAS in `live` mode. Please contact [support@fastenhealth.com](mailto:support@fastenhealth.com) or your [Account Representative](https://calendly.com/jason-kulatunga/30min) for more information.
## Overview
Bring Your Own Identity (BYOI) lets your application authenticate the patient at Authenticator Assurance Level 2 (AAL2)
and perform identity proofing with your own supported Credential Service Provider (CSP).
In the standard [TEFCA IAS flow](/guides/tefca-ias), Fasten sends the patient to a CSP such as CLEAR or ID.me and receives
the verified ID Token directly. In BYOI mode, your application owns that CSP experience. Your backend sends a stable
`patient_id` to Fasten's Identity service and receives a short-lived `request_uri` that can be passed into Fasten Stitch so
the patient can complete consent and provider selection.
Fasten uses the `patient_id` as the subject of a short-lived, Fasten-signed client assertion JWT and sends that JWT to your
registered Token Exchange endpoint. Your backend validates the assertion, uses the patient's active CSP authorization
grant to obtain a fresh CSP ID Token, and returns the ID Token to Fasten. Fasten can repeat this exchange when another CSP
ID Token is required during a long-running or later data collection request.
BYOI is intended for organizations that have completed TEFCA subparticipant onboarding and have a CSP configured to issue
ID Tokens with the organization's HCID in the `aud` claim. If you do not have that setup yet, use the standard
[TEFCA IAS flow](/guides/tefca-ias).
## How It Works
1. **Your application authenticates the patient (AAL2)** - The patient logs into their account within your product.
2. **Your application starts identity proofing** - Your product verifies their identity with your CSP.
3. **Your backend stores the CSP authorization grant** - Keep the patient's CSP ID Token and refresh token on your backend.
4. **Your backend creates a Pushed Authorization Request** - Call Fasten's Identity service with your stable `patient_id`.
5. **Fasten calls your preregistered Token Exchange endpoint** - Fasten sends a signed client assertion whose `sub` is the `patient_id`.
6. **Your endpoint validates the assertion and exchanges the active CSP grant** for a fresh CSP ID Token.
7. **Fasten validates the CSP ID Token** - The signature, issuer, expiration, audience, CSP, and environment must be valid.
8. **Fasten returns a `request_uri`** - The value is single-use, short-lived, and tied to your Fasten client.
9. **Your frontend launches Stitch** - You pass the `request_uri` into the Fasten SDK.
10. **Fasten collects patient consent** - The patient reviews your application and authorizes access.
11. **The patient selects providers** - Fasten searches the TEFCA network and guides the patient through selecting the healthcare organizations they want to share.
12. **Fasten repeats the Token Exchange when necessary** - Fasten may require a newly minted CSP ID Token to retrieve records from the TEFCA Network.
The initial exchange establishes the patient's CSP identity. Every CSP ID Token returned by a later exchange must contain
the same CSP `iss` and `sub` values. Within your organization, each `patient_id` must always identify the same patient and
must not be reassigned.
## Supported CSPs
The `idp` value in your Token Exchange response identifies the CSP that issued the returned ID Token.
| CSP | `idp` value |
| ------- | ------------- |
| CLEAR | `clear_csp` |
| ID.me | `idme_csp` |
| Persona | `persona_csp` |
The CSP must issue an unexpired OpenID Connect ID Token that Fasten can verify. The token audience must include your organization’s pre-configured HCID.
Use `test` credentials with synthetic CSP users and `live` credentials with real patient identities. Test mode rejects
non-synthetic email addresses.
## Prerequisites
Before you build the BYOI flow, make sure you have:
* Registered as a [TEFCA subparticipant](/guides/tefca-subparticipant) under Fasten with our QHIN.
* Authenticated the patient at AAL2 before submitting a Pushed Authorization Request.
* An [authorized CSP](https://rce.sequoiaproject.org/csp-approval-organizations/) that can complete IAL2 identity proofing.
* A CSP integration that can issue ID Tokens with `aud` set to your organization's HCID.
* Provided your organization's HCID to Fasten.
* Provided your HTTPS Token Exchange endpoint to Fasten.
* TEFCA IAS enabled for the Fasten API mode you are using.
* Generated a `public_*` ID and matching `private_*` key from the [Fasten Developer Portal](https://portal.fastenhealth.com).
Keep your `private_*` key and CSP credentials on your backend only.
## Stable Patient Identifier
The `patient_id` is your stable, opaque identifier for the patient. Fasten places it in the `sub` claim of every client
assertion sent to your Token Exchange endpoint, allowing your backend to locate the correct CSP authorization grant.
The value must:
* Be stable and unique within your organization.
* Resolve to exactly one patient and one active CSP authorization grant.
* Never be reassigned to another patient.
* Be safe to use as an opaque identifier; do not put an email address, name, or other patient data in it.
Fasten enforces a one-to-one mapping between your organization's `patient_id` and the patient's Fasten identity. A PAR
request fails if a `patient_id` is already associated with a different patient or if that patient is already associated
with a different `patient_id` for your organization.
Keep the `patient_id`, CSP tokens, Fasten private key, and CSP refresh credentials on backend systems. Do not send CSP or
Fasten credentials to browser or mobile client code.
## Developer Flow
### 1. Authenticate And Proof The Patient
Authenticate the patient at AAL2 and complete your CSP identity-proofing flow. Store the CSP authorization grant (ID Token
and refresh token) securely on your backend, indexed by the stable `patient_id` you send to Fasten. Your Token Exchange
endpoint uses this grant to obtain a new CSP ID Token whenever Fasten requests one.
You are responsible for managing the lifetime of the CSP ID Token and refresh token. If the underlying grant expires or
is revoked, the patient must authenticate again at AAL2 and complete any CSP authorization required to establish a new grant.
### 2. Create A Pushed Authorization Request
Call `POST https://identity.fastenhealth.com/oauth2/par` from your backend. Send an
`application/x-www-form-urlencoded` request using HTTP Basic authentication with your Fasten public ID and private key.
```bash theme={null}
curl -X POST https://identity.fastenhealth.com/oauth2/par \
-u "public_test_xxxxxxxxxx:private_test_xxxxxxxxxx" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "scope=openid profile email" \
--data-urlencode "response_type=code" \
--data-urlencode "prompt=consent" \
--data-urlencode "redirect_uri=https://customer.example.com/callback" \
--data-urlencode "patient_id=patient_01JAZ6Y3G2M4Q8K1V7N9"
```
#### Parameters
| Parameter | Required | Description |
| --------------- | -------- | -------------------------------------------------------------------- |
| `scope` | Yes | Must be `openid profile email`. |
| `response_type` | Yes | Must be `code`. |
| `prompt` | Yes | Must be `consent`. |
| `redirect_uri` | Yes | Must exactly match a redirect URI registered for your Fasten client. |
| `patient_id` | Yes | Your stable, opaque identifier for the patient. |
After validating the PAR request, Fasten immediately calls your registered Token Exchange endpoint. PAR fails if the
exchange cannot be completed or the returned CSP ID Token does not pass validation.
#### Response
A successful request returns `201 Created`.
```json theme={null}
{
"request_uri": "urn:ietf:params:oauth:request_uri:4c7f0f56-9302-4217-98d3-3b4d1e5f98ad",
"expires_in": 90
}
```
The `request_uri` is single-use and expires after 90 seconds.
### 3. Implement The Customer Token Exchange Endpoint
Your registered Token Exchange endpoint must:
* Use HTTPS.
* Accept `POST` requests with `application/x-www-form-urlencoded` bodies.
* Validate the Fasten-signed client assertion before accessing CSP credentials.
* Use the assertion's `sub` claim to locate the expected patient and their active CSP grant.
* Return a newly issued CSP ID Token.
Fasten sends a request in the following form:
```http theme={null}
POST /exchange/token HTTP/1.1
Host: identity.customer.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&
subject_token=eyJhbGciOiJSUzI1NiIsImtpZCI6...&
subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt&
requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token
```
The line breaks above are for readability. The actual request is a standard URL-encoded form body.
#### Validate Fasten's Client Assertion
The `subject_token` carries a short-lived client assertion JWT signed by Fasten. Validate:
| Field | Requirement |
| ---------- | ------------------------------------------------------------------------------------------------ |
| JOSE `alg` | Approved asymmetric signing algorithm. |
| JOSE `kid` | Must resolve to an active key in Fasten's JWKS. |
| `iss` | Must be `https://api.connect.fastenhealth.com`. |
| `sub` | Must be a valid `patient_id` issued by your system. |
| `aud` | Exact URL of your registered Token Exchange endpoint. |
| `exp` | Must be in the future and no more than five minutes after `iat`. |
| `iat` | Must be within five minutes of the current time, allowing up to 60 seconds of clock skew. |
| `nbf` | Must not be in the future beyond 60 seconds of clock skew. |
| `jti` | Must be present, unique, and rejected if previously used. |
| `task_id` | Optional. Present when Fasten requests an ID Token for an EHI Export or another background task. |
Cache each accepted `jti` until its assertion expires to prevent replay. Retrieve Fasten signing keys from
`https://identity.fastenhealth.com/jwks.json` and support normal key rotation. If an unknown `kid` is received, refresh
the JWKS once before rejecting the request.
An example decoded payload:
```json theme={null}
{
"iss": "https://api.connect.fastenhealth.com",
"sub": "patient_01JAZ6Y3G2M4Q8K1V7N9",
"aud": "https://identity.customer.example.com/exchange/token",
"exp": 1782298800,
"iat": 1782298500,
"nbf": 1782298440,
"jti": "7f13c12e-c359-46ab-b763-4ca479f566d8",
"task_id": "task_01JAZ78Q8G4H1MM2T5QF"
}
```
The `task_id` is context for logging and tracing purposes. It is optional, do not reference it for authorization;
validate the assertion signature, issuer, audience, lifetime, and replay status on every request.
#### Successful Response
Return `200 OK` and `Content-Type: application/json`
```json theme={null}
{
"id_token": "",
"idp": "clear_csp"
}
```
The `idp` must identify the CSP that issued the ID Token. Supported values are `clear_csp`, `idme_csp`, and
`persona_csp`.
#### Error Responses
Return OAuth-compatible JSON errors with `Cache-Control: no-store`.
```json theme={null}
{
"error": "invalid_grant",
"error_description": "The patient CSP authorization has expired or was revoked."
}
```
| HTTP status | Error | Use when |
| ----------- | ------------------------- | -------------------------------------------------------------------------------------------------- |
| `400` | `invalid_request` | Required form fields are missing, malformed, duplicated, or unsupported. |
| `400` | `invalid_grant` | The underlying CSP grant is expired, revoked, inactive, or not valid for the patient. |
| `400` | `unsupported_grant_type` | `grant_type` is not the RFC 8693 token-exchange grant. |
| `400` | `invalid_target` | The requested token type, CSP, audience, or resource is not allowed. |
| `401` | `invalid_client` | The Fasten client assertion is missing, invalid, expired, replayed, or signed by an untrusted key. |
| `429` | `temporarily_unavailable` | The endpoint is rate limiting Fasten. Include `Retry-After`. |
### 4. Pass The `request_uri` To Fasten Stitch
Initialize Fasten Stitch with the `request_uri` returned by the PAR response.
```html theme={null}
```
Redeem the `request_uri` immediately after your backend creates it. If the patient takes too long or refreshes the page, create a new PAR request and relaunch Stitch with the new value.
### 5. Handle Completion Events
Listen for the same Fasten Stitch events you use in other consent flows. Store the resulting `org_connection_id` and related metadata so your backend can request exports and support the patient later.
* Use `widget.complete` to update your frontend after Stitch finishes.
* Use [`patient.connection_success`](/webhooks/events#patient-connection-success-beta) as the durable backend signal.
* Store the resulting `org_connection_id`.
* Use [`POST /bridge/fhir/ehi-export`](/api-reference/ehi_export/create) when you are ready to retrieve records.
## On-Demand Refresh
Fasten calls the same registered Token Exchange endpoint whenever it requires a fresh CSP ID Token. Each request contains
a newly generated Fasten-signed client assertion with the original `patient_id` in `sub`. For an EHI Export or another
background task, the assertion may also contain a `task_id`.
Your endpoint must return an ID Token for the same CSP identity established by the initial exchange. Fasten rejects a
refreshed token if its CSP `iss` or `sub` differs from the initial token, even if the token is otherwise valid.
Your EHI Export request only needs the Fasten API credentials and `connection_id`; you are not required to send a CSP ID Token in the
/ehi-export request. Fasten retrieves a fresh token from your Token Exchange endpoint when needed. If the endpoint cannot
return a valid token, collection fails and the patient must reauthenticate with your CSP.
Token Exchange endpoint implementations must be safe when Fasten retries a request or makes concurrent requests:
* Do not assume a request is delivered exactly once.
* Coordinate access to rotating CSP refresh tokens.
* Persist a replacement CSP refresh token before invalidating the previous stored value.
* Return the same successful result when safely possible, or perform another valid CSP exchange.
* Do not revoke the patient grant merely because a request timed out or was retried.
Fasten may retry temporary failures and rate-limited requests. Use `Retry-After` with `429 Too Many Requests` or
`503 Service Unavailable` when Fasten should delay the next attempt.
## Security And Operations
* Keep your Fasten private key on your backend.
* Keep the `patient_id` stable and never associate it with a different person.
* Return CSP ID Tokens only from your backend Token Exchange endpoint.
* Treat the CSP ID Token as sensitive patient identity data.
* Fasten receives the verified ID Token, not the patient’s ID photos or CSP proofing session materials.
## Implementation Checklist
* Complete TEFCA subparticipant and BYOI onboarding.
* Register the Token Exchange endpoint, organization HCID, and supported CSP with Fasten.
* Authenticate patients to AAL2.
* Issue stable, opaque, never-reassigned `patient_id` values.
* Store each patient's active CSP authorization grant securely on your backend.
* Implement Fasten client assertion validation and `jti` replay protection using Fasten's JWKS.
* Return the CSP ID Token and `idp` in the Token Exchange response.
* Verify retry and concurrent-refresh behavior with rotating CSP refresh tokens.
* Re-verify the patient when the CSP grant expires or is revoked.
* Keep all Fasten and CSP credentials on backend systems.
## Standards
* [OAuth 2.0 Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693.html)
* [JWT Profile for OAuth 2.0 Client Authentication (RFC 7523)](https://www.rfc-editor.org/rfc/rfc7523.html)
* [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
* [NIST Digital Identity Guidelines: Authentication and Authenticator Management](https://pages.nist.gov/800-63-4/sp800-63b.html)
For Fasten-managed identity proofing, see the [TEFCA IAS Developer Guide](/guides/tefca-ias).
# Introduction
Source: https://docs.connect.fastenhealth.com/identity-proofing/introduction
Learn when identity proofing is required, why it helps protect healthcare data, and what patients should expect.
There are additional fees involved with TEFCA IAS in `live` mode. Please contact [support@fastenhealth.com](mailto:support@fastenhealth.com) or your [Account Representative](https://calendly.com/jason-kulatunga/30min) for more information
## Overview
Fasten has the capability to access medical records from a variety of data sources with patient consent.
Some of these sources require Identity Proofing as an additional step to confirm that the patient requesting records is the same person whose records are being accessed.
For customers who have enabled these optional data sources, Fasten will prompt patients to verify their identity through
a secure third-party provider before they can select records to share. This process typically involves taking a photo of a
government-issued ID and a selfie, which the provider uses to confirm the patient's identity.
Identity proofing is not a credit check and does not affect a patient's care, insurance, or credit score. It is a security
step used to protect access to sensitive health information.
## Why Healthcare Uses Identity Proofing
Healthcare records contain highly sensitive information. Identity proofing helps make sure access is granted to the right
person before data is shared across organizations.
For patients, identity proofing can make record access easier because a successful verification may allow records to be
found across participating healthcare organizations without signing in to each patient portal separately.
For customers building with Fasten, identity proofing helps support:
* **Patient trust** - Patients see a clear step explaining why their identity is being verified.
* **Data protection** - Higher-assurance identity checks reduce the risk of unauthorized access.
* **Better matching** - Verified identity attributes can improve matching against participating healthcare data sources.
* **Network access** - Some data sources require proofed identity before they will release patient records.
* **Cleaner consent records** - The proofing event becomes part of a more auditable access workflow.
## When Patients May See It
A patient may be asked to complete identity proofing when:
* They are using a Fasten-powered flow that connects to a data source requiring verified identity.
* They are requesting records through a network access flow such as TEFCA IAS.
* Your application uses [Bring Your Own Identity](/identity-proofing/bring-your-own-identity)
If identity proofing is not required for the selected data source, the patient will continue through the normal Fasten
Connect experience.
## What Patients Should Have Ready
Patients should complete identity proofing in a well-lit place with a stable internet connection.
They may need:
* A valid government-issued photo ID, such as a driver's license, state ID, or passport.
* A smartphone or computer with a working camera.
* Access to the email address and phone number they use for verification.
* Their current legal name, date of birth, and home address.
* A few uninterrupted minutes to complete the proofing flow.
If the patient has already verified with the selected identity provider, they may only need to sign in and confirm their
account instead of repeating the full document and selfie capture process.
## What To Expect
The exact screens vary by identity provider, but most proofing flows follow a similar path.
### 1. Choose An Identity Provider
The patient may be asked to choose or continue with an identity provider. The available options depend on the data source,
customer configuration, and Fasten environment.
### 2. Prepare Documents
The identity provider explains what the patient needs before proofing begins. This is usually a photo ID, camera access,
and a phone or email verification method.
### 3. Capture A Photo ID
The patient takes a clear photo of their government-issued ID. The identity provider checks that the document appears
valid and readable.
### 4. Take A Selfie
The patient may be asked to take a selfie or short live image so the identity provider can compare the person completing
the flow to the photo ID.
### 5. Return To Fasten
After successful proofing, the patient returns to Fasten to review consent and continue selecting the records or providers
they want to share.
## Customer Implementation Notes
Set patient expectations before launching identity proofing. The best place to do this is in your application, immediately
before opening the Fasten Connect experience.
Recommended customer-facing guidance:
* Explain that identity proofing may be required for some data sources, not every connection.
* Ask patients to have a valid photo ID and camera-ready device available.
* Make clear that proofing helps protect access to health records.
* Provide a support path if a patient cannot complete verification.
## Privacy And Security FAQs
No. Identity proofing is optional functionality used only for data sources and workflows that require a higher-confidence identity check.
Many Fasten Connect flows continue to use standard patient portal sign-in and consent without an additional proofing step.
Some healthcare data sources require stronger proof that the person requesting records is the patient or an authorized individual.
This helps protect sensitive health information from unauthorized access.
No. Identity proofing is used only to confirm identity for record access. It is not a credit check and does not affect care, insurance eligibility, or credit score.
The identity proofing provider handles the document and selfie capture during the verification flow. Fasten receives the verification result and identity information needed to continue the record-access workflow.
Fasten does not need photo ID images or selfie images to complete the record-access workflow. The identity proofing provider may process and retain verification materials according to its own privacy policy and legal obligations.
Fasten receives the information required to confirm the verified identity and continue the consent flow. This may include verified identity attributes such as name, date of birth, email, address, and a proofing result or token, depending on the provider and workflow.
If the selected data source requires identity proofing, the patient must complete it before records can be requested through that flow. If proofing is optional for the selected connection, the patient can continue through the standard Fasten Connect flow.
The patient can usually retry, correct unreadable images, or choose another available verification method. If they still cannot complete proofing, they should contact the application support team for help.
Yes. Fasten uses secure authorization flows and encrypted connections to handle identity and consent information.
## Next Steps
* Use [TEFCA IAS](/guides/tefca-ias) when Fasten should manage the identity proofing redirect.
* Use [Bring Your Own Identity](/identity-proofing/bring-your-own-identity) when your application performs AAL2 authentication and proofing with your own supported CSP.
# Quickstart
Source: https://docs.connect.fastenhealth.com/quickstart
Start collecting medical records in under 5 minutes
## Introduction
Let’s get you started with Fasten Connect!
This guide will walk you through the process of setting up your Fasten Connect account, configuring your API credentials, and requesting a patient's medical records.
You’ll need API keys, which you can receive by signing up in the [Developer Portal](https://portal.fastenhealth.com).
We also have a NodeJS Quickstart repo available for customers that would like to jump straight into the code.
### Fasten Connect API Modes
The Fasten Connect API has two modes: `test` and `live`. Test mode is used for development and testing, while live mode is used for production.
Test mode secret keys have the prefix `private_test_` and live mode secret keys have the prefix `private_live_`.
| API Key Prefix | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `public_test_` | Test mode client-side key that uniquely identifies your app |
| `private_test_` | Test mode server-side key allows you to make authenticated requests. **Must be kept secret** |
| API Key Prefix | Description |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `public_live_` | Live mode client-side key that uniquely identifies your app |
| `private_live_` | Live mode server-side key allows you to make authenticated requests. **Must be kept secret** |
### Create API Credentials
1. Sign up for a Fasten Connect account in the [Developer Portal](https://portal.fastenhealth.com).
2. Click the Developer tab and then the `Create Credentials` button. You must provide a `Redirect URL`, which is the URL that Fasten Connect will redirect the user to after they have successfully linked their account.
3. Make note of the public id and private key generated for you. **The private key is only shown once, so make sure to save it in a secure location.**
### Webhook Configuration
1. In the Developer Portal, click the `Create Webhook` button. You must provide a `Webhook URL`, which is the URL that Fasten Connect will send events to.
If you do not have a public URL to use, you can use a service like [smee.io](https://smee.io/) or [requestbin.com](https://public.requestbin.com/r) to create a temporary public URL for testing.
### Fasten Stitch configuration
[Fasten Stitch](/stitch/v4/introduction) is the client-side component that your users will interact with in order to link their
accounts to Fasten Connect and allow you to access their accounts via the Fasten Connect API.
To get started, you'll need to add the Fasten Stitch component to your website. You can do this by adding the following
code snippet to your website's HTML. Replace `public_test_123456324234234` with your own public key, which you can find
in the [Developer Portal](https://portal.fastenhealth.com).
```md stitch.js theme={null}
```
The `fasten-stitch-element` HTML element will render a button that your users can click to link their accounts to Fasten Connect.
### Initial Connection
When the user clicks the button, they will be shown a search box and being the process to authenticate and authorize your app to access
their data.
#### Redirect to Patient Portal
After selecting health system, and clicking "Sign In" you will be redirected to a patient portal where you can login with patient credentials (username + password).
#### Test Patient Credentials
In `test` mode, you can use the following credentials to test the Fasten Stitch component:
| Source | Credentials / Sandbox Status | Link |
| ---------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| AdvancedMD | Username: Password: | |
| Aetna | Username: `VTETestUser01` Password: `FHIRdemo2020` | [test accounts](https://developerportal.aetna.com/sandbox_v2_test_member_logins_and_test_data_v2.1.xlsx) |
| AllScripts | Username: Password: | |
| Anthem | Username: `HOSPatient` Password: `HOSPatient2023` | |
| AthenaHealth | Username: `phrtest_preview@mailinator.com` Password: `Password1` | [test accounts](https://docs.athenahealth.com/api/guides/onboarding-overview) |
| CareEvolution | Username: `CEPatient` Password: `CEPatient2018` | [test accounts](https://fhir.careevolution.com/TestPatientAccounts.html) |
| Cerner | Username: `nancysmart` Password: `Cerner01` | [test accounts](https://docs.google.com/document/d/10RnVyF1etl_17pyCyK96tyhUWRbrTyEcqpwzW-Z-Ybs/edit) |
| Cigna | Username: `syntheticuser05` Password: `5ynthU5er5` | [test accounts](https://developer.cigna.com/service-apis/patient-access/sandbox#How-to-Use-the-Sandbox-Sandbox-Test-Users) |
| DynamicHealthIT | Username: Password: | |
| eClinicalWorks/Healow | Username: `AdultFemaleFHIR` Password: `e@CWFHIR1` | [test accounts](https://connect4.healow.com/apps/jsp/dev/r4/fhirClinicalDocumentation.jsp#SandboxTestingGuidelines) |
| Epic | Username: `fhircamila` Password: `epicepic1` | [test accounts](https://fhir.epic.com/Documentation?docId=testpatients) |
| Flatiron/OncoEMR | Username: Password: | |
| HealthIT | Username: `demouser` Password: `Demouser1!` | [test accounts](https://fhirsandbox.healthit.gov/secure/r4/view/userlogin.html) |
| Humana | Username: `HUser00001` Password: `PW00001!` | |
| Kaiser | Username: `Pvaluser1` Password: `V@lidation1` | |
| Logica | Username: Password: | |
| MaximEyes | Username: Password: | |
| Medhost | Username: Password: | |
| Medicare | Username: `BBUser00000` Password: `PW00000!` | [test accounts](https://bluebutton.cms.gov/developers/#developer-guidelines) |
| Meditech | Username: Password: | |
| Netsmart | Username: Password: | |
| NextGen | Username: `patientapitest` Password: `Password1!` | [test accounts](https://www.nextgen.com/-/media/files/api/nge-patient-api-auth-guide.pdf) |
| PracticeFusion/PatientFusion | Username: Password: | |
| VA Health | Provider: ID.me Username: `va.api.user+101-2024@gmail.com` Password: `Password12345!!!` | [test accounts](https://developer.va.gov/explore/api/patient-health/test-users/3617/7058f75892b845dbbd3f371703cc066f398c336a87bb51d73128f1bac24e3105) |
Once the user has successfully linked their account, the `fasten-stitch-element` will generate a javascript event containing
information about connection. This payload will contain a `org_connection_id` identifier that
you can use to make requests to the Fasten Connect API.
### Parse Stitch.js Javascript Event Payload
Connection events will be sent to your frontend code via Javascript events.
The events can be handled by modifying the `eventBus` event listener in the code snippet above.
```html theme={null}
```
In your frontend code you must process the Stitch.js browser [Event](/stitch/v4/sdks/web-component/reference#patient-connection-success).
```json widget.complete Event theme={null}
{
"api_mode": "live",
"event_type": "widget.complete",
"data": [{
"org_connection_id": "fedec7b7-8cf6-4bc9-9058-72032b426473",
"endpoint_id": "8e2f5de7-46ac-4067-96ba-5e3f60ad52a4",
"brand_id": "e16b9952-8885-4905-b2e3-b0f04746ed5c",
"portal_id": "2727ec27-67e9-475a-bea1-423102beaa1d",
"connection_status": "authorized",
"platform_type": "epic"
}]
}
```
You must store the `data.org_connection_id` fields by sending it to your backend, as it is required for subsequent requests
to the Fasten API to request medical records for this individual patient.
You may also want to store the other fields for future reference, such as `endpoint_id`, `brand_id`, `portal_id` and `platform_type`.
Learn more about [Stitch.js Events](/stitch/v4/sdks/web-component/reference#widget-complete)
### Requesting Patient Bulk Export
Fasten Connect allows you to request a bulk export of a patient's medical records. To do this, you'll need to make a POST
request to the [`/bridge/fhir/ehi-export` endpoint](/api-reference/ehi_export/create) with the `org_connection_id` of the patient whose records you want to export.
This process is asynchronous, so you can wait for the webhook event to be sent to your webhook URL, or you can poll the
`/bridge/fhir/ehi-export/{org_connection_id}` endpoint to check the status of the export.
Request to the `/bridge/fhir/ehi-export` endpoint must be authenticated with your private key. Here's an example using `curl`:
```bash curl theme={null}
# Note: `-u` is shorthand for `--user` and can be used to avoid manually encoding the credentials, and passing the Authorization header.
curl -u 'public_test_123456324234234':'private_test_9u2orj....sd02lk3)i03423' \
-X POST \
--data '{"org_connection_id":"ebea708d-c5fa-4294-9051-da48ef08c78a"}' \
https://api.connect.fastenhealth.com/v1/bridge/fhir/ehi-export
```
Try it out yourself in the [API Playground](/api-reference/ehi_export/create).
### Async Webhook Event
When the export is complete, Fasten Connect will `POST` a [webhook event](/webhooks) to the URL you provided when creating the webhook.
The event will contain the `task_id` and the `download_links` of the export that was completed.
The export is only stored for 24h, so make sure to download the export as soon as you receive the webhook event.
```json webhook-event.json theme={null}
{
"api_mode": "test",
"type": "patient.ehi_export_success",
"date": "2024-04-03T17:16:40Z",
"id": "1b37cf9b-702f-4fd1-bb00-d0fd8e6dbc89",
"data": {
"download_links": [{
"url": "https://api.connect.fastenhealth.com/v1/bridge/fhir/ehi-export/fedec7b7-8cf6-4bc9-72032b426473/download/2024-06-12-6715-4ae4-bde5-ab97519bd1fa.jsonl",
"export_type": "jsonl",
"content_type": "application/fhir+ndjson"
}],
"task_id": "c9c7a91b66b34fdca749bb8e9cfbf617",
"org_id": "d65008f6-ffb1-4cd8-b868-c2de66fa5155"
}
}
```
Learn more about [Webhooks & Events](/webhooks)
### Downloading the Export
Once you recieve the webhook event, you can use the `download_links` to download the export. The export will be a JSONL file
containing the patient's medical records in FHIR format.
This method requires authentication with your private key. Make sure to keep your private key secure and do not expose it in your client-side code.
The download link will redirect to a signed URL that is only valid for a short period of time (10 minutes).
You can request a new signed URL by making another authenticated request to the [download endpoint](/api-reference/ehi_export/download).
```bash curl theme={null}
# Note: `-u` is shorthand for `--user` and can be used to avoid manually encoding the credentials, and passing the Authorization header.
# Note: The --location flag is used to follow redirects. Your http client must be able to follow the redirect and download the file from our blob storage (S3).
curl -o patient_bulk_export.jsonl \
-u 'public_test_123456324234234':'private_test_9u2orj....sd02lk3)i03423' \
--location \
https://api.connect-dev.fastenhealth.com/v1/bridge/fhir/ehi-export/c9c7a91b66b34fdca749bb8e9cfbf617/download/2024-04-03-098c09ef-887d-4aad-886c-d3ffd11750da.jsonl
```
View Patient EHI Export Example
[Click here](https://gist.github.com/AnalogJ/1fe4b4da2878dc021f6f4fe6538ee37f) to download an example EHI Export file in JSONL format.
It was previously generated via the Fasten Connect API and contains medical records from the Epic Sandbox in FHIR format.
## TEFCA Mode
Now that you have completed the Quickstart Guide you can (optionally) enable TEFCA-mode with a single line change.
When TEFCA mode is enabled, developers can access medical records without requiring the patient to search for their healthcare providers, or login to multiple portal logins.
Instead the patient is prompted to verify their identity and Fasten Connect will automatically retrieve their medical records from any healthcare institution that participates in the TEFCA network.
# Client Events
Source: https://docs.connect.fastenhealth.com/stitch/v4/client-events
Events generated by the Fasten Stitch SDKs.
# Events
The Stitch component will communicate with your frontend application using Client-Side Events ([Javascript Events](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Events) in the Web Component SDK and [React Events](https://react.dev/learn/responding-to-events) in React Native SDK).
Stitch SDKs will generate a variety of events that you react to via an Event Listener (`addEventListener()`).
```html Web Component SDK theme={null}
```
```typescript React Native SDK theme={null}
{
console.log('Fasten event', event);
}}
/>
```
### patient.connection\_pending
This event is emitted when the patient has begun the process to connect and the popup window has closed.
```json theme={null}
{
"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 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 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
TEFCA When connecting in TEFCA mode, this field may be omitted.
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
TEFCA When connecting in TEFCA mode, this field may be omitted.
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.
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.
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.
```json theme={null}
{
"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": ""
}
}
```
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 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 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
TEFCA When connecting in TEFCA mode, this field may be omitted.
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
TEFCA When connecting in TEFCA mode, this field may be omitted.
The status of the connection. Possible values are `authorized`, `revoked`.
An identifier for the EHR type associated with the connected endpoint.
An correlation id. This should be sent with any support ticket queries to the Fasten Connect support team.
(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.html](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html)
Only 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`.
(Optional) This will be an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.8) 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.
(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.
```json theme={null}
{
"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 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 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 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
The status of the connection. Possible values are `authorized`, `revoked`.
An identifier for the EHR type associated with the connected endpoint.
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.
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`
The `error_description` parameter can only include ASCII characters, and will be a sentence or two at most describing the circumstance of the error.
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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"api_mode": "live",
"event_type": "search.query",
"data": {
"query": "search term",
"timestamp": 1674123456,
"filter": {
"locations": ["CA"]
},
"results": {
"total": 4
},
"external_id": ""
}
}
```
# Introduction
Source: https://docs.connect.fastenhealth.com/stitch/v4/introduction
Overview of the Stitch SDKs for embedding Fasten Connect experiences in Web, React, React Native, and future runtimes.
This documentation is for [Stitch.js (v4) SDK](/stitch/v4/), which is now the recommended version for integrating Fasten Connect into your application.
If you need access to the previous versions, please see [v1 documentation](/stitch/v1/) or [v3 documentation](/stitch/v3/).
This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.
v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.
The [v1 Web Component](/stitch/v1/) and [v3 Web Component](/stitch/v3) are in maintenance mode and will no longer receive updates (outside of security fixes).
Please update your code to use the new version.
## Welcome
Fasten Stitch is the client-side component that your users will interact with in order to link their accounts to Fasten Connect and
allow you to access their medical records via the Fasten Connect API.
Stitch handles patient consent, credential validation, multi-factor authentication, and error handling for each institution that
Fasten Connect supports. Stitch v4 ships as multiple SDKs so you can embed the same experience across browsers, React apps, and native shells.
To try Stitch, see Fasten Connect [Acme Demo](https://www.acmelabsdemo.com/v4/).
## SDK catalog
Choose the SDK that best matches your runtime. Each SDK exposes the same events and configuration surface, so once you understand the
core concepts you can reuse them everywhere.
* [Web Component SDK](/stitch/v4/sdks/web-component/quickstart) — Embed `` inside any web page or web view.
* [React SDK](/stitch/v4/sdks/react/quickstart) Beta — Render Stitch with typed React props, refs, and component-level styling.
* [React Native SDK](/stitch/v4/sdks/react-native/quickstart) — Present Stitch as a native modal powered by the same event bus.
We will continue to add additional SDKs underneath `/stitch/v4/sdks/` as new platforms become available.
Stitch is the recommended method for collecting medical records via Fasten Connect.
```html Web Component theme={null}
```
```tsx React Native theme={null}
import React, { useCallback } from 'react';
import { StyleSheet, View } from 'react-native';
import {FastenStitchElement} from '@fastenhealth/fasten-stitch-element-react-native';
export default function App() {
const CUSTOMER_PUBLIC_ID = "public_test_xxxxxxxx";
const handleEventBus = useCallback((message: unknown) => {
console.debug('[FastenStitchElement onEventBus] message', message);
}, []);
return (
);
}
```
```tsx React theme={null}
import { FastenStitchElement } from '@fastenhealth/fasten-stitch-element-react';
export default function App() {
const CUSTOMER_PUBLIC_ID = "public_test_xxxxxxxx";
return (
{
const payload = JSON.parse(event.data);
console.debug('[FastenStitchElement onEventBus] payload', payload);
}}
/>
);
}
```
# Quickstart
Source: https://docs.connect.fastenhealth.com/stitch/v4/sdks/react-native/quickstart
Install the Stitch React Native SDK and launch the Fasten Connect modal from iOS and Android apps.
This documentation is for [Stitch.js (v4) SDK](/stitch/v4/), which is now the recommended version for integrating Fasten Connect into your application.
If you need access to the previous versions, please see [v1 documentation](/stitch/v1/) or [v3 documentation](/stitch/v3/).
This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.
v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.
The [v1 Web Component](/stitch/v1/) and [v3 Web Component](/stitch/v3) are in maintenance mode and will no longer receive updates (outside of security fixes).
Please update your code to use the new version.
The React Native SDK implements an experience similar to the `` component, but designed specifically for React Native. You can provide a familiar mobile
flow without maintaining a web surface. It forwards the same event
payloads that the Web Component emits.
## Installation
```bash theme={null}
# npm
npm install @fastenhealth/fasten-stitch-element-react-native react-native-webview
# yarn
yarn add @fastenhealth/fasten-stitch-element-react-native react-native-webview
```
If you are using bare React Native, run `npx pod-install` so iOS picks up the native dependencies. Expo Managed apps only need to
rebuild if you add the optional native module for secure storage.
## Basic usage
Wrap your application (or the portion that should be able to trigger Stitch) with the provider that ships in the SDK. The provider
accepts the standard Stitch configuration values and wires up a shared modal instance you can control from anywhere in your tree.
```tsx theme={null}
import { FastenStitchElement } from 'fasten-connect-stitch-react-native';
const CUSTOMER_PUBLIC_ID = 'public_test_...';
export const ConnectScreen = () => (
{
console.log('Fasten event', event);
}}
/>
);
```
The hook returns an object with helpers for presenting/dismissing the modal and exposes the latest `isVisible` state so you can toggle
secondary UI (disabling buttons, showing spinners, etc.).
## Basic usage (TEFCA Mode)
When TEFCA mode is enabled, developers can access medical records without requiring the patient to search for their healthcare providers, or login to multiple portal logins.
Instead the patient is prompted to verify their identity and Fasten Connect will automatically retrieve their medical records from any healthcare institution that participates in the TEFCA network.
If you would like to enable TEFCA IAS mode, you can do so by setting the `tefcaMode="true"` configuration option.
The remaining installation steps are the same as above, just with the additional attribute.
This is intentionally designed to be as simple as possible to get started with TEFCA IAS.
```tsx theme={null}
import { FastenStitchElement } from 'fasten-connect-stitch-react-native';
const CUSTOMER_PUBLIC_ID = 'public_test_...';
export const ConnectScreen = () => (
{
console.log('Fasten event', event);
}}
/>
);
```
# Reference
Source: https://docs.connect.fastenhealth.com/stitch/v4/sdks/react-native/reference
Configuration options, events, and styling guidance for the Stitch React Native SDK
This documentation is for [Stitch.js (v4) SDK](/stitch/v4/), which is now the recommended version for integrating Fasten Connect into your application.
If you need access to the previous versions, please see [v1 documentation](/stitch/v1/) or [v3 documentation](/stitch/v3/).
This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.
v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.
The [v1 Web Component](/stitch/v1/) and [v3 Web Component](/stitch/v3) are in maintenance mode and will no longer receive updates (outside of security fixes).
Please update your code to use the new version.
```tsx theme={null}
import { FastenStitchElement } from 'fasten-connect-stitch-react-native';
const CUSTOMER_PUBLIC_ID = 'public_test_...';
export const ConnectScreen = () => (
{
console.log('Fasten event', event);
}}
/>
);
```
This must be your API public ID. You can find it in your [Fasten Connect Portal](https://portal.fastenhealth.com).
(Optional) Useful when the patient connection credentials are invalid (due to expiration or revocation). Providing this `reconnectOrgConnectionId` allows Fasten to reauthenticate the Patient and store their new credentials.
Reconnect When provided, the stitch component will skip the search step and go directly to the reauthentication step for the specified organization connection.
(Optional) An Opaque identifier, used to identify the patient in your system. This value will be returned in the response.
(Optional) The patient's email address. When provided, Fasten Connect prepopulates email fields in the TEFCA mode page, support request form, and health system request form. The patient can edit the prepopulated value before submitting a form.
(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.
(Optional) Prepopulate the search box with a query.
(Optional) Show a splash page introduces Fasten Connect and displays your privacy policy & terms to the patient before they begin the connection process.
(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 receive 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.
(Optional/Recommended) This callback is called whenever the Stitch component emits an event. The callback receives a fully-parsed JSON object containing the event data.
(Optional) If set to `true`, the stitch component will operate in TEFCA IAS mode, which is a streamlined experience designed to simplify medical record collection.
In this mode, the patient will be able to verify their identity and pull medical records from healthcare institutions that participate in the TEFCA network, with minimal friction.
See the [TEFCA IAS documentation](/guides/tefca-ias) for more information on this experience and its benefits.
## Events
The Stitch React Native SDK emits client-side events that can be listened to in your React Native application.
The events are emitted on via the `onEventBus` callback you can pass to the `FastenStitchElement` component. The callback receives a fully-parsed JSON object containing the event data.
```ts theme={null}
onEventBus={(event: StitchEvent) => {
console.log('Fasten event', event);
}}
```
See the [Events section of the documentation](/stitch/v4/client-events) for more information on the events emitted by the Stitch SDK and their payloads.
# Quickstart
Source: https://docs.connect.fastenhealth.com/stitch/v4/sdks/react/quickstart
Install the Stitch React SDK and launch the Fasten Connect modal from React web apps.
This documentation is for [Stitch.js (v4) SDK](/stitch/v4/), which is now the recommended version for integrating Fasten Connect into your application.
If you need access to the previous versions, please see [v1 documentation](/stitch/v1/) or [v3 documentation](/stitch/v3/).
This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.
v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.
The [v1 Web Component](/stitch/v1/) and [v3 Web Component](/stitch/v3) are in maintenance mode and will no longer receive updates (outside of security fixes).
Please update your code to use the new version.
The React SDK renders a trigger button that opens the Fasten Connect widget in a modal dialog. It is designed for React web applications that want typed props, React refs, and component-level styling instead of using the Web Component directly.
## Installation
```bash theme={null}
# npm
npm install @fastenhealth/fasten-stitch-element-react
# yarn
yarn add @fastenhealth/fasten-stitch-element-react
```
React 18 or later is required as a peer dependency.
## Basic usage
Render `FastenStitchElement` anywhere you want the patient to start a connection flow. The default trigger button opens the Stitch modal and the `onEventBus` callback receives the raw browser `MessageEvent` from the embedded widget.
```tsx theme={null}
import { FastenStitchElement } from '@fastenhealth/fasten-stitch-element-react';
const CUSTOMER_PUBLIC_ID = 'public_test_...';
export function ConnectRecords() {
return (
{
const payload = JSON.parse(event.data);
console.log('Fasten event', payload);
}}
/>
);
}
```
## Custom trigger
Pass `children` when you want to use your own button or link as the trigger. The SDK wraps the children in a clickable element and still owns the modal lifecycle.
```tsx theme={null}
import { FastenStitchElement } from '@fastenhealth/fasten-stitch-element-react';
export function ConnectRecords() {
return (
);
}
```
## Programmatic control
The component exposes `show()` and `hide()` through a React ref.
```tsx theme={null}
import { useRef } from 'react';
import {
FastenStitchElement,
type FastenStitchElementHandle,
} from '@fastenhealth/fasten-stitch-element-react';
export function ConnectRecords() {
const stitchRef = useRef(null);
return (
<>
);
}
```
## Basic usage (TEFCA Mode)
When TEFCA mode is enabled, developers can access medical records without requiring the patient to search for their healthcare providers, or login to multiple portal logins.
Instead the patient is prompted to verify their identity and Fasten Connect will automatically retrieve their medical records from any healthcare institution that participates in the TEFCA network.
If you would like to enable TEFCA IAS mode, set `tefcaMode={true}`. The remaining installation steps are the same as above, just with the additional prop.
```tsx theme={null}
import { FastenStitchElement } from '@fastenhealth/fasten-stitch-element-react';
const CUSTOMER_PUBLIC_ID = 'public_test_...';
export function ConnectRecords() {
return (
{
const payload = JSON.parse(event.data);
console.log('Fasten event', payload);
}}
/>
);
}
```
# Reference
Source: https://docs.connect.fastenhealth.com/stitch/v4/sdks/react/reference
Configuration options, events, refs, and styling guidance for the Stitch React SDK.
This documentation is for [Stitch.js (v4) SDK](/stitch/v4/), which is now the recommended version for integrating Fasten Connect into your application.
If you need access to the previous versions, please see [v1 documentation](/stitch/v1/) or [v3 documentation](/stitch/v3/).
This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.
v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.
The [v1 Web Component](/stitch/v1/) and [v3 Web Component](/stitch/v3) are in maintenance mode and will no longer receive updates (outside of security fixes).
Please update your code to use the new version.
Beta
```tsx theme={null}
import { FastenStitchElement } from '@fastenhealth/fasten-stitch-element-react';
export function ConnectRecords() {
return (
{
const payload = JSON.parse(event.data);
console.log('Fasten event', payload);
}}
/>
);
}
```
This must be your API public ID. You can find it in your [Fasten Connect Portal](https://portal.fastenhealth.com).
(Optional) An opaque identifier used to identify the patient in your system. This value will be returned in the response.
(Optional) The patient's email address. When provided, Fasten Connect prepopulates email fields in the TEFCA mode page, support request form, and health system request form. The patient can edit the prepopulated value before submitting a form.
(Optional) Useful when the patient connection credentials are invalid due to expiration or revocation. Providing this `reconnectOrgConnectionId` allows Fasten to reauthenticate the patient and store their new credentials.
Reconnect When provided, the Stitch component will skip the search step and go directly to the reauthentication step for the specified organization connection.
(Optional) Pre-select a specific brand.
(Optional) Pre-select a specific portal.
(Optional) Pre-select a specific endpoint.
(Optional) Prepopulate the search box with a query.
(Optional) Sort search results by a specific field.
(Optional) JSON-encoded sort options for `searchSortBy`. The SDK automatically Base64URL-encodes this value before sending it to Stitch.
(Optional) Show a splash page that introduces Fasten Connect and displays your privacy policy and terms to the patient before they begin the connection process. Defaults to `false`.
(Optional) If set to `true`, the Stitch component will operate in TEFCA IAS mode, which is a streamlined experience designed to simplify medical record collection.
In this mode, the patient will be able to verify their identity and pull medical records from healthcare institutions that participate in the TEFCA network, with minimal friction.
See the [TEFCA IAS documentation](/guides/tefca-ias) for more information on this experience and its benefits. Defaults to `false`.
(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 receive optional events, set `eventTypes` 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.
(Optional) If set to `true`, the modal will not close when the patient clicks outside of the dialog. Defaults to `false`.
(Optional) Text for the default trigger button. Ignored when `children` is provided. Defaults to `Share Records`.
(Optional) Custom class name for the trigger button. When supplied, the SDK does not apply default button styles unless you also pass `buttonStyle`.
(Optional) Custom inline styles for the trigger button.
(Optional) Custom class name for the `` element. When supplied, the SDK does not apply default dialog styles unless you also pass `dialogStyle`.
(Optional) Custom inline styles for the `` element.
(Optional) Custom class name for the `` element. When supplied, the SDK does not apply default iframe styles unless you also pass `iframeStyle`.
(Optional) Custom inline styles for the `` element.
(Optional) Custom trigger UI rendered instead of the default button.
## Events
The Stitch React SDK emits client-side events through the `onEventBus` callback. The callback receives the raw browser `MessageEvent` sent by the embedded widget.
```tsx theme={null}
onEventBus={(event) => {
const payload = JSON.parse(event.data);
console.log('Fasten event', payload);
}}
```
See the [Events section of the documentation](/stitch/v4/client-events) for more information on the events emitted by the Stitch SDK and their payloads.
## Javascript API
Use `FastenStitchElementHandle` when you need to open or close the modal programmatically.
```tsx theme={null}
import { useRef } from 'react';
import {
FastenStitchElement,
type FastenStitchElementHandle,
} from '@fastenhealth/fasten-stitch-element-react';
export function ConnectRecords() {
const stitchRef = useRef(null);
return (
<>
);
}
```
Opens the connect modal and loads the embedded Stitch widget.
Closes the connect modal and resets the iframe source.
## Styling
The SDK includes default styles for the trigger button, modal dialog, iframe, focus states, hover states, and dialog backdrop. You can customize these with class name or inline style props.
```tsx theme={null}
```
The React SDK renders a trigger element, a native ``, and an ``. You can style the trigger, dialog, and iframe, but you will not be able to style content within the iframe.
# Quickstart
Source: https://docs.connect.fastenhealth.com/stitch/v4/sdks/web-component/quickstart
Install and render the `` inside any web runtime.
This documentation is for [Stitch.js (v4) SDK](/stitch/v4/), which is now the recommended version for integrating Fasten Connect into your application.
If you need access to the previous versions, please see [v1 documentation](/stitch/v1/) or [v3 documentation](/stitch/v3/).
This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.
v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.
The [v1 Web Component](/stitch/v1/) and [v3 Web Component](/stitch/v3) are in maintenance mode and will no longer receive updates (outside of security fixes).
Please update your code to use the new version.
## Installation
```md stitch.js theme={null}
```
## Installation (TEFCA Mode)
When TEFCA mode is enabled, developers can access medical records without requiring the patient to search for their healthcare providers, or login to multiple portal logins.
Instead the patient is prompted to verify their identity and Fasten Connect will automatically retrieve their medical records from any healthcare institution that participates in the TEFCA network.
If you would like to enable TEFCA IAS mode, you can do so by adding the `tefca-mode="true"` attribute to the `` tag.
The remaining installation steps are the same as above, just with the additional attribute.
This is intentionally designed to be as simple as possible to get started with TEFCA IAS.
```md stitch.js theme={null}
```
# Reference
Source: https://docs.connect.fastenhealth.com/stitch/v4/sdks/web-component/reference
Configuration options, events, and styling guidance for the Stitch Web Component.
This documentation is for [Stitch.js (v4) SDK](/stitch/v4/), which is now the recommended version for integrating Fasten Connect into your application.
If you need access to the previous versions, please see [v1 documentation](/stitch/v1/) or [v3 documentation](/stitch/v3/).
This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.
v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.
The [v1 Web Component](/stitch/v1/) and [v3 Web Component](/stitch/v3) are in maintenance mode and will no longer receive updates (outside of security fixes).
Please update your code to use the new version.
```html theme={null}
```
This must be your API public ID. You can find it in your [Fasten Connect Portal](https://portal.fastenhealth.com).
(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.
Reconnect When provided, the stitch component will skip the search step and go directly to the reauthentication step for the specified organization connection.
(Optional) An Opaque identifier, used to identify the patient in your system. This value will be returned in the response.
(Optional) The patient's email address. When provided, Fasten Connect prepopulates email fields in the TEFCA mode page, support request form, and health system request form. The patient can edit the prepopulated value before submitting a form.
(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.
(Optional) Prepopulate the search box with a query.
(Optional) Show a splash page introduces Fasten Connect and displays your privacy policy & terms to the patient before they begin the connection process.
(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.
(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 receive 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.
(Optional) If set to `true`, the stitch component will operate in TEFCA IAS mode, which is a streamlined experience designed to simplify medical record collection.
In this mode, the patient will be able to verify their identity and pull medical records from healthcare institutions that participate in the TEFCA network, with minimal friction.
See the [TEFCA IAS documentation](/guides/tefca-ias) for more information on this experience and its benefits.
## Events
The Stitch Web Component emits Javascript events that can be listened to in your frontend code.
The events are emitted on the `fasten-stitch-element` DOM element, and can be listened to using the `addEventListener` method.
```javascript theme={null}
const el = document.querySelector('fasten-stitch-element');
el.addEventListener('eventBus', (event) => console.log(event.detail));
```
See the [Events section of the documentation](/stitch/v4/client-events) for more information on the events emitted by the Stitch SDK and their payloads.
## 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.
```javascript theme={null}
window.addEventListener('DOMContentLoaded',function () {
//show the modal using the element selector.
document.querySelector('fasten-stitch-element').show();
});
```
#### hide()
Hide the modal popup.
```javascript theme={null}
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.
```html theme={null}
```
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 `` tags. For example:
```html theme={null}
Connect My Health Records
```
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.
# Support
Source: https://docs.connect.fastenhealth.com/support
How to get support for Fasten Connect
### Fasten Connect Support
Fasten Connect provides comprehensive support to ensure a smooth integration experience:
* **Service Level Agreements (SLAs) & Business Associate Agreements (BAAs):** Available for customers on upgraded plans.
* **Email Support:** Reach out to us anytime at [support@fastenhealth.com](mailto:support@fastenhealth.com).
* **Slack Support:** We recommend Slack for real-time assistance. We'll set up a shared Slack channel to help you get started and address your questions.
* **Hands-On Assistance:** Our team is ready to guide you through your integration, answer questions, and share best practices.
* **Status Page:** Check our [status page](https://status.fastenhealth.com/) for real-time updates on system performance and any ongoing incidents.
We're committed to providing the support you need to succeed with Fasten Connect.
### What to include when requesting support
When contacting support, include any relevant identifiers so Fasten engineers can quickly locate the affected organization, connection, task, or request:
* `organization_id`: Your customer identifier. This helps us debug billing, payment, and webhook-related issues.
* `org_connection_id`: The patient consent or authorization identifier used to access a patient's records. This helps us debug patient consent and data collection errors.
* `task_id`: The worker task identifier generated when calling `/ehi-export`. This is only useful for data collection errors, especially when investigating a `patient.ehi_export_success` or `patient.ehi_export_failed` webhook event.
* `request_id`: The HTTP client correlation identifier, also known as a trace ID. This helps us debug specific API endpoint errors, including `4xx` or `5xx` responses, and can be useful for patient consent errors.
# Delivery
Source: https://docs.connect.fastenhealth.com/webhooks/delivery
This section helps you understand different behaviors of Fasten Connect webhook delivery & provides some best practices.
## Delivery Logs
You can view the delivery logs of your webhook endpoints in the [Developer Portal](https://portal.fastenhealth.com).
The logs provide information about the delivery status of each event, including the response code, response body, and response headers.
Delivery logs are only available for the last 15 days.
Check our Webhook Debugging & Simulator Guide for more details on how to use delivery logs and the webhook simulator.
## Duplicate Events
Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts
by logging the event IDs you’ve processed, and then not processing already-logged events.
## Select Specific Event Types
Configure your webhook endpoints to receive only the types of events required by your integration.
Listening for extra events (or all events) puts undue strain on your server and we don’t recommend it.
You can change the events that a webhook endpoint receives in the [Developer Portal](https://portal.fastenhealth.com).
## Handle Events Asynchronously
Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously.
Any large spike in webhook deliveries (for example, during the beginning of the week when Patient Credentials are refreshed) might overwhelm your endpoint.
Asynchronous queues allow you to process the concurrent events at a rate your system can support.
## Verify Events
Verify webhook signatures to confirm that received events are sent from Fasten Connect. Fasten Connect signs webhook events it sends to
your endpoints by including a signature in each event’s `Webhook-Signature` header. This allows you to verify that the events
were sent by Fasten Connect, not by a third party. You can verify signatures either using our official libraries, or verify manually using your own solution.
See [Webhook Verification](/webhooks/verification) for more information.
## Respond Immediately
Your endpoint must quickly return a successful status code (`200`) prior to any complex logic that could cause a timeout.
For example, you must return a `200` response before processing the JSONL payload and storing the data in your database.
## ⚠️ Webhook Auto-Disable Policy
To keep things running smoothly, we automatically disable webhooks that repeatedly fail.
### What Counts as a Failure
* No 2xx HTTP response
* Response takes longer than 60 seconds
* Connection errors
We retry each event up to 4 times. If your webhook keeps failing, it gets disabled.
### If Disabled…
You’ll get an email alert. To re-enable, fix the issue and toggle it back on from Developers > `Webhooks` section in your dashboard.
Need help? You can email us at: [support@fastenhealth.com](mailto:support@fastenhealth.com)
# Event Types
Source: https://docs.connect.fastenhealth.com/webhooks/events
There are multiple event types that can be emitted by Fasten Connect.
## patient.ehi\_export\_success
```json theme={null}
{
"download_links": [{
"url": "https://api.connect.fastenhealth.com/v1/bridge/fhir/ehi-export/fedec7b7-8cf6-4bc9-72032b426473/download/2024-06-12-6715-4ae4-bde5-ab97519bd1fa.jsonl",
"export_type": "jsonl",
"content_type": "application/fhir+ndjson"
}],
"org_connection_id": "189484f4-1234-1234-1234-78a8caa3b64a",
"task_id": "fedec7b78cf6905872032b426473",
"org_id": "592c0579-443f-a94e-4c8847c0c066",
"stats": {
"total_resources": 12,
"total_by_resource_type": {
"AllergyIntolerance": 1,
"Binary": 8,
"CarePlan": 1,
"CareTeam": 1,
"Condition": 7,
"DiagnosticReport": 4,
"DocumentReference": 7,
"Encounter": 5,
"Goal": 12,
"Immunization": 1,
"Location": 6,
"Medication": 1,
"MedicationRequest": 1,
"Observation": 248,
"Organization": 3,
"Patient": 1,
"Practitioner": 8,
"Procedure": 2
}
}
}
```
This is a an array containing a URL to download the medical records that Fasten has collected for the Patient.
Your http client should be able to follow the redirect and download the file.
By default, this will be a JSONL(NDJSON) file containing FHIR resources in newline-delimited format (each line is a independent JSON object).
The array will only contain one entry by default, but you may enable multiple formats by contacting Fasten support.
The URL of the medical records download file.
The type of file being provided. Possible values are:
* `jsonl`: Newline-delimited JSON (NDJSON) file containing FHIR resources.
* other formats can be enabled by contacting Fasten support.
The MIME type of the file being provided.
This is an object containing statistics about the resources processed and collected by Fasten.
This field is deprecated. Please use `download_links` instead.
## patient.ehi\_export\_failed
```json theme={null}
{
"failure_reason": "suppressed_please_contact",
"org_connection_id": "189484f4-1234-1234-1234-78a8caa3b64a",
"task_id": "fedec7b78cf6905872032b426473",
"org_id": "592c0579-443f-a94e-4c8847c0c066"
}
```
Failure reason for the EHI export. This is a `enum` that describes the failure.
The possible values are:
* `token_refresh_failure`: An error is encountered while trying to refresh the Access Token.
* `scope_patient_missing`: The Access Token does not have the required `patient/*.read` or `patient/Patient.read` scope. This is usually due to the patient unchecking the "Demographics" permission during the Consent flow.
* `resource_patient_failure`: An error occurred while trying to fetch a patient resource. This is unusual because the token (likely) refreshed successfully.
* `resource_invalid_content`: Parsing issue in a critical FHIR resource
* `tefca_no_documents_found`: TEFCA Returned only when TEFCA mode is enabled. The health system did not return any records for the individual. This is frequently seen in `test` mode, but is uncommon in `live` mode. When testing the API workflow, you can often avoid this by setting `fixtures.tefca_ccda` on the EHI Export request to force a known synthetic response.
* `suppressed_please_contact`: The error was suppressed, as it may contain PII or PHI. This is the default value for `failure_reason`. Please contact Fasten support for more information.
## webhook.test
```json theme={null}
{
"hello": "world",
"random": "txpsdf923jksdfl93"
}
```
## patient.connection\_success
This event is emitted when the patient has successfully connected to the health system and the popup window has closed.
Failures are not yet available as a webhook event.
This event is not enabled by default.
You may enable this event in the Fasten Connect dashboard by toggling the "patient.connection\_success" option for your webhook.
```json theme={null}
{
"org_connection_id": "",
"endpoint_id": "",
"brand_id": "",
"portal_id": "",
"connection_status": "",
"platform_type": "",
"request_id": "",
"external_id": "",
"scope": "",
"consent_expires_at": "",
"tefca_directory_id": ""
}
```
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 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 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
TEFCA When connecting in TEFCA mode, this field may be omitted.
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
TEFCA When connecting in TEFCA mode, this field may be omitted.
The status of the connection. Possible values are `authorized`, `revoked`.
An identifier for the EHR type associated with the connected endpoint.
An correlation id. This should be sent with any support ticket queries to the Fasten Connect support team.
(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.
Usually a generated identifier, can use it to identify unique connection attempts.
(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.html](https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html)
Only 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`.
(Optional) This will be an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.8) 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.
(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.authorization\_revoked
This event is emitted when the patient consent has been revoked or expired.
Fasten connect will refresh patient tokens on a regular basis, and if the refresh fails due to revoked or expired consent, this event will be emitted.
Your system should be prepared to handle multiple revocation events in a short period of time, as Fasten may revoke connections in bulk for multiple patients at once.
This event is not enabled by default.
You may enable this event in the Fasten Connect dashboard by toggling the "patient.authorization\_revoked" option for your webhook.
```json theme={null}
{
"org_connection_id": "",
"endpoint_id": "",
"portal_id": "",
"brand_id": "",
"platform_type": "",
"connection_status": ""
}
```
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 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 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
TEFCA When connecting in TEFCA mode, this field may be omitted.
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
TEFCA When connecting in TEFCA mode, this field may be omitted.
An identifier for the EHR type associated with the connected endpoint.
The status of the connection. Will always be `revoked`.
## patient.request\_health\_system
This event is emitted when a patient initiates a request to add a missing health system.
```json theme={null}
{
"email": "john.doe@example.com",
"name": "My Health System",
"website": "https://www.examplehealthsystem.com",
"street_address": "123 Main St, Anytown, USA"
}
```
The email address provided by the patient to contact them about their request.
The name of the health system requested by the patient.
The website URL of the health system requested by the patient.
The street address of the health system requested by the patient.
## patient.request\_support (beta)
This event is emitted when a patient requests support during the connection process
```json theme={null}
{
"email": "john.doe@example.com",
"name": "My Health System",
"body": "(patient message & request metadata, subject to change) I need help with..."
}
```
The email address provided by the patient to contact them about their support request.
The name of the health system the patient was trying to connect to when they requested support.
The body of the support request, containing the patient's message and any relevant metadata. The format of this data is arbitrary and subject to change.
**Warning**: This field may contain Personally Identifiable Information (PII) or Protected Health Information (PHI). Handle with care and in accordance with applicable regulations & your security policy.
# Introduction
Source: https://docs.connect.fastenhealth.com/webhooks/introduction
Use Webhooks to listen to events from Fasten Connect, rather than polling the API.
## Why Use Webhooks?
When building applications using Fasten Connect, you'll need to configure a webhook to receive events.
Since collecting medical records from Health Systems can take time, webhooks allow you to wait for the data to be available,
without wasting time and resources by polling the API.
To enable webhook events, you need to register a webhook in the [Developer Portal](https://portal.fastenhealth.com).
Fasten Connect uses HTTPS to `POST` webhook events to your app as a JSON payload that includes an Event object.
## Payload Overview
All webhook payloads contain a common set of fields wrapping the event data. The `event` object contains the event type and the data associated with the event.
```json theme={null}
{
"api_mode": "test",
"date": "2024-06-13T00:08:31Z",
"id": "c0ac7bc4-c6ef-4f0b-bba3-93506774eb74",
"type": "patient.ehi_export_success",
"data": {
"download_links": [{
"url": "https://api.connect.fastenhealth.com/v1/bridge/fhir/ehi-export/fedec7b7-8cf6-4bc9-72032b426473/download/2024-06-12-6715-4ae4-bde5-ab97519bd1fa.jsonl",
"export_type": "jsonl",
"content_type": "application/fhir+ndjson"
}],
"task_id": "fedec7b78cf6905872032b426473",
"org_id": "592c0579-c1cc-443f-a94e-4c8847c0c066"
}
}
```
The Fasten Connect API has two modes: `test` and `live`. Test mode is used for development and testing, while live mode is used for production.
This field will always be present in the payload and will indicate the mode of the API that generated the event.
This will be an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339.html#section-5.8) timestamp that encodes the date & time the payload delivery was attempted.
**This may not be when the event was created.** The timestamp of the attempt may be different to the timestamp of the event that generated the attempt.
One common example of where this happens: failed deliveries. Every time an attempt is retried the timestamp of the attempt
is updated, while the timestamp of the original event remains the same. The attempt's timestamp as an important security measure meant to prevent replay attacks.
The `id` is a UUIDv4 that uniquely identifies the event. This is useful for idempotency, to ensure that you don't process the same event multiple times.
It remains the same no matter how many times a webhook that has failed is retried.
[Event Types](/webhooks/events) indicate the type of the event being sent in the webhook and the schema of the `data` field.
See `type` and [Event Types](/webhooks/events) documentation to find out what fields are present in the `data` object.
# Verification
Source: https://docs.connect.fastenhealth.com/webhooks/verification
Verify webhook signatures to confirm that received events are sent from Fasten Connect
Webhooks are just HTTP requests from an unknown source, so verifying the authenticity of webhooks is a requirement for any secure webhook implementation.
## Retrieving your endpoint’s secret
Find the Webhooks section of the [Developer Portal](https://portal.fastenhealth.com). Click the `Developer Logs` for the endpoint that you want
to obtain the secret for, and find the `Signing Secret` on the top right of the `Delivery Logs` page.
Fasten Connect generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys,
the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one
you want to verify signatures for.
## Preventing replay attacks
A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such
attacks, Fasten Connect includes a timestamp in the `Webhook-Signature` header. Because this timestamp is part of the signed payload,
it's also verified by the signature, so an attacker can’t change the timestamp without invalidating the signature.
If the signature is valid but the timestamp is too old, you can have your application reject the payload.
Fasten Connect generates the timestamp and signature each time we send an event to your endpoint. If Fasten Connect retries an
event (for example, your endpoint previously replied with a non-200 status code), then we generate a new signature and timestamp for the new delivery attempt.
## Verification
Fasten Connect webhooks conform to the [Standard-Webhooks specification](https://www.standardwebhooks.com/), which means
that you can use any of the libraries that implement the specification to verify the webhook signatures.
See the [Standard-Webhooks libraries](https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries) page for a list of libraries that you can use to verify webhook signatures.
```javascript JavaScript theme={null}
import { Webhook } from "standardwebhooks"
const wh = new Webhook(secret);
wh.verify(webhook_payload, webhook_headers);
```
```go Golang theme={null}
import (
standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go"
)
wh, err := standardwebhooks.NewWebhook(secret)
err = wh.Verify(webhookPayload, webhookHeaders)
```
```python Python theme={null}
from standardwebhooks.webhooks import Webhook
wh = Webhook(secret)
wh.verify(webhook_payload, webhook_headers)
```
```ruby Ruby theme={null}
require "standardwebhooks"
wh = StandardWebhooks::Webhook.new(secret)
wh.verify(webhook_payload, webhook_headers)
```
```java Java theme={null}
import com.standardwebhooks.Webhook;
Webhook webhook = new Webhook(secret);
webhook.verify(webhookPayload, webhookHeaders);
```
,
};