> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connect.fastenhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Types

> 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
      }
    }
}
```

<ResponseField name="download_links" type="object[]" required>
  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 <a href="mailto:support@fastenhealth.com">Fasten support</a>.

  <Expandable title="Download Link Properties">
    <ResponseField name="url" type="string">
      The URL of the medical records download file.
    </ResponseField>

    <ResponseField name="export_type" type="string">
      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 <a href="mailto:support@fastenhealth.com">Fasten support</a>.
    </ResponseField>

    <ResponseField name="content_type" type="string">
      The MIME type of the file being provided.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="stats" type="object" required>
  This is an object containing statistics about the resources processed and collected by Fasten.
</ResponseField>

<ResponseField name="download_link" type="object" deprecated>
  This field is deprecated. Please use `download_links` instead.
</ResponseField>

## 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"
}
```

<ResponseField name="failure_reason" type="string" required>
  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`: <Badge color="green">TEFCA</Badge> 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.
</ResponseField>

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

<Warning>
  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.
</Warning>

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

<ResponseField name="org_connection_id" type="string" required>
  Organization Connection Id is a unique identifier for the connection between the patient and the organization.
  You must store this value in your system to identify the patient in future API calls.
</ResponseField>

<ResponseField name="endpoint_id" type="string" required>
  Endpoint Id is a unique identifier for the endpoint that the patient has connected to.
  This value can be used to retrieve metadata about the endpoint (e.g. name, description, endpoint url information, etc.)

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="portal_id" type="string" required>
  Portal Id is a unique identifier for the Portal that the patient has connected to.
  This value can be used to retrieve branding information about the institution

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="brand_id" type="string" required>
  Brand Id is a unique identifier for the Brand that the patient has connected to.
  This value can be used to retrieve branding information about the institution

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="connection_status" type="string" required>
  The status of the connection. Possible values are `authorized`, `rejected`.
</ResponseField>

<ResponseField name="platform_type" type="string" required>
  An identifier for the EHR type associated with the connected endpoint.
</ResponseField>

<ResponseField name="request-id" type="string">
  An correlation id. This should be sent with any support ticket queries to the Fasten Connect support team.
</ResponseField>

<ResponseField name="external_id" type="string">
  (Optional) An Opaque identifier, used to identify the patient in your system.
  This value will be only be returned if it was previously provided to the stitch html element.
</ResponseField>

<ResponseField name="external_state" type="string" required>
  Usually a generated identifier, can use it to identify unique connection attempts.
</ResponseField>

<ResponseField name="scope" type="string">
  (Optional) The OAuth2 scope that was granted by the patient during the connection process.
  See [https://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.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.

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field will always be present and will contain the value `patient/*.read`.
</ResponseField>

<ResponseField name="consent_expires_at" type="string">
  (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.
</ResponseField>

<ResponseField name="tefca_directory_id" type="string">
  (Optional) The TEFCA Directory ID of the health system that the patient connected to.

  <Badge color="green">TEFCA</Badge> 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.
</ResponseField>

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

<Warning>
  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.
</Warning>

```json theme={null}
{
    "org_connection_id": "",
    "endpoint_id": "",
    "portal_id": "",
    "brand_id": "",
    "platform_type": "",
    "connection_status": ""
}
```

<ResponseField name="org_connection_id" type="string" required>
  Organization Connection Id is a unique identifier for the connection between the patient and the organization.
  You must store this value in your system to identify the patient in future API calls.
</ResponseField>

<ResponseField name="endpoint_id" type="string">
  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.)

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="portal_id" type="string">
  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

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="brand_id" type="string">
  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

  <Badge color="green">TEFCA</Badge> When connecting in TEFCA mode, this field may be omitted.
</ResponseField>

<ResponseField name="platform_type" type="string" required>
  An identifier for the EHR type associated with the connected endpoint.
</ResponseField>

<ResponseField name="connection_status" type="string" required>
  The status of the connection. Will always be `revoked`.
</ResponseField>

## 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"

}
```

<ResponseField name="email" type="string" required>
  The email address provided by the patient to contact them about their request.
</ResponseField>

<ResponseField name="name" type="string" required>
  The name of the health system requested by the patient.
</ResponseField>

<ResponseField name="website" type="string">
  The website URL of the health system requested by the patient.
</ResponseField>

<ResponseField name="street_address" type="string">
  The street address of the health system requested by the patient.
</ResponseField>

## 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..."
}
```

<ResponseField name="email" type="string" required>
  The email address provided by the patient to contact them about their support request.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the health system the patient was trying to connect to when they requested support.
</ResponseField>

<ResponseField name="body" type="string" required>
  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.
</ResponseField>