​
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.

​
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 PrefixDescription
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

​
Create API Credentials

  1. Sign up for a Fasten Connect account in the Developer Portal.
  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 or requestbin.com to create a temporary public URL for testing.

​
Fasten Stitch configuration

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 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.
stitch.js
<html>
<head>
    <link href="https://cdn.fastenhealth.com/connect/v3/fasten-stitch-element.css" rel="stylesheet">
    <script src="https://cdn.fastenhealth.com/connect/v3/fasten-stitch-element.js" type="module"></script>
</head>
<body>
    <!-- The fasten-stitch-element element has multiple options,
    see Web Component page for more information -->
    <fasten-stitch-element public-id="public_test_123456324234234"></fasten-stitch-element>

    <script type="application/javascript">
        const el = document.querySelector('fasten-stitch-element');
        el.addEventListener('eventBus', (event) => console.log(event.detail.data));
    </script>
</body>
</html>
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:
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. 
    <script type="application/javascript">
        const el = document.querySelector('fasten-stitch-element');
        el.addEventListener('eventBus', (event) => {
            console.log(event.detail.data)
            // NOTE: the fasten event data will be present in the `event.detail.data` string (not `event`)
            // You will need to parse the event.detail.data string as JSON to access the fields

            // YOUR CUSTOM LOGIC HERE
            let eventPayload = JSON.parse(event.detail.data)
            if(eventPayload.event_type == 'widget.complete') {
                console.log(eventPayload.event_type);
            } else if(eventPayload.event_type == 'widget.close') {
                console.log(eventPayload.event_type);
            }
        });
    </script>
In your frontend code you must process the Stitch.js browser Event.
widget.complete Event
{
  "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

​
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 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:
curl
# 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.

​
Async Webhook Event

When the export is complete, Fasten Connect will POST a webhook event to the URL you provided when creating the webhook. The event will contain the task_id and the download_link 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.
webhook-event.json
{
    "api_mode": "test",
    "type": "patient.ehi_export_success",
    "date": "2024-04-03T17:16:40Z",
    "id": "1b37cf9b-702f-4fd1-bb00-d0fd8e6dbc89",
    "data": {
        "download_link": "https://api.connect.fastenhealth.com/v1/bridge/fhir/ehi-export/c9c7a91b66b34fdca749bb8e9cfbf617/download/2024-04-03-098c09ef-887d-4aad-886c-d3ffd11750da.jsonl",
        "task_id": "c9c7a91b66b34fdca749bb8e9cfbf617",
        "org_id": "d65008f6-ffb1-4cd8-b868-c2de66fa5155"
    }
}
Learn more about Webhooks & Events

​
Downloading the Export

Once you recieve the webhook event, you can use the download_link 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.
curl
# 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 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.