Welcome to the Foundation Health API, providing access to the Foundation Health Platform.

We set out to make it as easy as possible for you to integrate with our platform and deliver the features it offers to your patients. By focussing on connecting you to the world of healthcare through our open and accessible platform, we empower you to create exceptional patient experiences.

We're excited to collaborate with partners like you who share our vision of transforming the patient experience. Our API platform is at the core of our business, and we can't wait for you to begin using it. We're here to ensure your integration process is seamless. If you have any questions, feel free to reach out to us at contactus@foundationhealth.com

The Foundation Health Platform provides a set of RESTful, JSON-based APIs that can be used to interact with our network of pharmacies and telehealth providers in regions around the world. They are designed to be both flexible and consistent, supporting a wide range of workflows and use cases across multiple countries.

The platform supports common workflows such as submitting a telehealth consultation which we pass through to an appropriate healthcare professional; ordering medications to be delivered to your patients; requesting prescription refills, and more.

A generalised workflow for a telehealth consultation with prescribing and dispensing might look like this:

1. Create a Patient record for your patient.
2. Submit a Consultation Response containing information collected from the patient via an async Consultation.
3. Make a Prescription Request for the medication(s) the Patient requires.
4. Once notified (via webhook) that the Prescription Request has been approved, place an Order.

This workflow can be adapted to support OTC products, prescription transfers, or any number of other scenarios. Talk to us to learn how we can support your use case.

Note that the API is intentionally not versioned, instead we operate an additive philosophy. This ensures all customers have access to the latest features without the need to upgrade versions or deal with breaking changes.

At Foundation Health, our commitment to the security and confidentiality of Protected Health Information (PHI) is unwavering. We prioritize the integrity of your data at all times, and we take the responsibility of protecting it very seriously.

Our approach ensures strict compliance with the regulations in the various countries and regions in which we operate; including those outlined in the General Data Protection Regulations (GDPR). We take pride in providing a secure environment for your healthcare interactions, offering peace of mind to both you and your patients.

We store only the data required to facilitate your requests, and share only the necessary subset of data with your approved telehealth and/or pharmacy partners. Data is encrypted at rest with multiple levels of encryption; and in transit by TLS 1.2+. We rely on industry leading authentication solutions from Okta and Google to restrict access to the API. Customer data is carefully segregated, and isolated by region, to ensure that it is only accessible to you and does not leave the jurisdiction in which your patients reside.

A rate limit of 1024 requests per minute is in place to protect the API from abuse. If this limit is exceeded, API requests will temporarily receive a 429: Too Many Requests response.

In order to access the Foundation Health API, you will need a set of credentials which will be provisioned and provided to you during the onboarding process. Please reach out to us at contactus@foundationhealth.com to start the onboarding process and get your API credentials.

You will be provided with credentials for two environments specific to the region in which you operate:

• A production environment, eg https://api-us.foundationhealth.com
• A sandbox environment, eg https://sandbox-us.foundationhealth.com

The sandbox environment is functionally a mirror of the production environment, but intended only for use with test data. It can be used for developing your initial integration, end-to-end testing and any other non-production purposes. Note that test data may be removed from the sandbox environment periodically.

Once you have your credentials, you can begin making requests to the API. Start by checking out the Authentication section to see how to obtain an access token. Then see Patients to learn about managing patient records; Consultations for more on submitting health data; Prescribing for how to work with prescriptions; and Fulfillment for everything related to placing orders.

This API Changelog is an overview of changes made to the Foundation Health API. It is intended to help you keep track of changes that may affect your integration.

The Foundation Health API uses the OAuth 2.0 Client Credentials flow for authentication. Begin by requesting an ID token from the /auth/token endpoint with your client_id and client_secret. The token can be cached and reused until it expires (typically after 10 minutes, the actual expiry time is included in the exp claim of the token JWT). All requests to the Foundation Health API must include an ID token in the Authorization header.

Create, view and manage Patients. A Patient is the subject of a Prescription Request or Consultation Response, and the intended recipient of an Order.

Create new Consultation Responses. A Consultation comprises of Questions to be posed to the Patient, and covers certain products. You must use a Consultation which is appropriate for the product you are issuing to the Patient. For example, Consultation cons_picbnjwp72xk8ulfmvni0cc1 might cover the product SKU ab-cd-01 (a medication for erectile dysfunction), whereas Consultation cons_awcab2f6rfdldf49hhpxulkf might cover the product SKU xy-09-76 (a medication for hair loss). Contact Foundation Health to discuss which Consultation to use for your product.

Create new Prescription Requests and view the resulting Prescriptions.

An electronic prescription (eRx) represents digitally the generation, transmission, and filing of a prescription. In the US, the accepted standard for eRx is the “SCRIPT standard,” governed by the National Council for Prescription Drug Programs (NCPDP). Other regions have similar standards, such as the Electronic Prescription Service (EPS) in the UK; or may rely on the transmission of cryptographically signed PDF documents.

Electronic prescriptions can be written by our telehealth partners via a Prescription Request, transferred from another pharmacy, or sent by any licensed provider to our pharmacy partners via the Surescripts network. Talk with us to discuss the best approach for your use case.

If a new Prescription is required for the item(s) in an Order, then you must first submit a Prescription Request. An approved Prescription Request results in a Prescription. You will be notified of approval or rejection via webhook events, rejections may include a reason for the rejection if provided by the prescriber.

Place, view and manage Orders and their shipments. An Order is a request to ship one or more items to a Patient. An Order can be created with or without a Prescription, however if a Prescription is required for the item(s) in the Order, then you must first have submitted a Prescription Request and received a Prescription. An Order can be created with or without a Consultation Response, however if a Consultation Response is required for the item(s) in the Order, then you must first have submitted a Consultation Response for the appropriate Consultation. You will be notified as the Order is processed via a webhook.

Foundation Health will notify you of important events via a registered webhook. Webhook URLs must be manually registered for your account as part of the onboarding process. The platform supports registering multiple webhook URLs per environment.

Note: An API is being developed for you to register and manage your own webhook URLs in future.

Events are sent as Signed JSON Web Tokens (JWS) via a HTTPS POST request. They will be sent with the Content-Type: application/jose header.

An example payload will look like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicHJlc2NyaXB0aW9uX3JlcXVlc3RfYXNzaWduZWQiLCJkYXRhIjp7InByZXNjcmlwdGlvblJlcXVlc3RJZCI6InJ4cmVxX2xxZGllOTdibjZpcjJkZ3U0bmxtamVpNyJ9LCJpYXQiOjE3MDA1NjMxNDd9.jar6b0YkRYtacR-FYplonVzzk0GnAu79DDnnR2vNA4w

You must verify the JWT signature using the secret you will have been issued when the webhook is registered to your account. This guarantees the webhook was received from Foundation Health and has not been tampered with.

Once the signature is verified you can safely decode & parse the payload as a JSON object. Example decoded payloads are documented below.

After a webhook event has been received, it must be acknowledged by responding with a successful (2XX) status code. Events which are not acknowledged with a successful status code will be resent up to 10 times, in an attempt to ensure that the event is received successfully.

The following event types are currently provided:

Example webhook event payloads are provided below (Note that the examples assume you have verified & decoded the JWT payload):

Your request has been received by our prescribing partner and will be reviewed by a prescriber in due course. Typically this will happen immediately after you submit a Prescription Request. For sync prescription requests where the Prescriber provides a link for the Patient to schedule a visit, the event will include a scheduling link in the schedulingLink property.

{
  "type": "prescription_request_assigned",
  "data": {
    "prescriptionRequestId": "rxreq_1234567890",
    "prescriptionRequestDownstreamId": "downstream_123",
    "schedulingLink": "https://example.com/schedule" | undefined
  }
}

A prescriber has reviewed your request and determined that the requested medication is not suitable for the patient; or it is otherwise not possible to issue a prescription for the requested medication. The reason for rejection given by the prescriber will be included in the event reason property. You may wish to contact the patient to notify them and check the details they provided were accurate.

{
  "type": "prescription_request_rejected",
  "data": {
    "prescriptionRequestId": "rxreq_1234567890",
    "reason": "The patient is not suitable for this medication." | undefined,
    "prescriptionRequestDownstreamId": "downstream_123" | undefined
  }
}

Note: A reason will always be included where we receive one from the Prescriber but certain Partners in our network may not provide this information.

The Prescription Request was denied without being sent to a Prescriber for review. The reason for denial will be included in the event reason property. Typically this occurs when the patient or consultation response fail some sort of pre-check performed by the telehealth partner.

{
  "type": "prescription_request_denied",
  "data": {
    "prescriptionRequestId": "rxreq_1234567890",
    "reason": "The Patient is not eligible for a new visit" | undefined,
  }
}

Note: A reason will always be included where we receive one from the telehealth partner; but in some cases no reason is given.

A new prescription is created; either as a result of a prescriber reviewing a request and issuing a Prescription, or a Prescription received from an external source. You can now place an Order for the prescribed medication(s) using the prescriptionId included in the event.

Measured quantities are expressed in physical units, given by the quantityUnitOfMeasure property, and using a 3 decimal place precision.

{
  "type": "prescription_created",
  "data": {
    "prescriptionId": "rx_1234567890",
    "prescriptionRequestId": "rxreq_1234567890" | undefined,
    "productIds": ["semaglutide_2.5mg_1ml"],
    "prescribedMedication": {
      "productSku": "semaglutide_2.5mg_1ml",
      "medicationId": "med_zydk6vb0u2up4imsj6ed6mk0" | undefined,
      "quantity": 2,
      "daysSupply": 3 | undefined,
      "measuredQuantity": "2.000",
      "quantityUnitOfMeasure": "ml",
      "refills": {
        "quantityPerFill": 1,
        "measuredQuantityPerFill": "1.000",
        "numberOfFills": 2
      }
    }
  }
}

Your order has been received and accepted by our fulfillment partner.

{
  "type": "order_assigned",
  "data": {
    "upstreamId": "ord_upstream_123",
    "orderId": "ord_1234567890",
    "downstreamId": "downstream_123",
  }
}

In the unlikely event an Order is sent to a partner for fulfillment, but cannot be fulfilled. This may be because the order has failed pharmacist verification for example. Where a reason for the rejection is given by the partner it will be included in the event reason property.

{
  "type": "order_rejected",
  "data": {
    "orderId": "ord_1234567890",
    "upstreamId": "ord_upstream_123",
    "reason": "Contraindication between dispensed medication and existing medication" | undefined,
    "downstreamId": "downstream_123" | undefined,
    "requisitionDownstreamId": "requisition_downstream_123" | undefined
  }
}

Certain Pharmacies have specific conditions that must be met before an Order can be sent to them. In the unlikely event these conditions are not met by your Order, you will receive an order_denied event. The reason property will provide more information about the reason for the denial.

{
  "type": "order_denied",
  "data": {
    "orderId": "ord_1234567890",
    "upstreamId": "ord_upstream_123",
    "reason": "Patient is not old enough"
  }
}

Your order cancellation request was approved and the order is now cancelled.

{
  "type": "order_cancellation_approved",
  "data": {
    "upstreamId": "ord_upstream_123",
    "orderId": "ord_1234567890",
    "downstreamId": "downstream_123" | undefined,
  }
}

Your order cancellation request failed, so the order cannot be cancelled. The failure reason will be included in the event's reason property.

{
  "type": "order_cancellation_failed",
  "data": {
    "upstreamId": "ord_upstream_123",
    "orderId": "ord_1234567890",
    "reason": "The order has already been dispatched, and can no longer be canceled",
    "downstreamId": "downstream_123" | undefined,
  }
}

A Shipment has been created for an Order and is ready to be shipped. Most orders will result in one shipment, multiple shipments usually occur if you plan to offer split-shipping or are combining multiple product types in a single order. If using a tracked delivery method the tracking number and/or URL will be included in the event and any subsequent shipment_shipped & shipment_delivered events.

{
  "type": "shipment_created",
  "data": {
    "orderId": "ord_1234567890",
    "shipmentId": "ship_1234567890",
    "shippingService": "DHL Express" | undefined,
    "trackingId": "1234567890" | undefined,
    "trackingUrl": "https://www.dhl.com/en/express/tracking.html?AWB=1234567890" | undefined,
    "orderDownstreamId": "downstream_123"
  }
}

A Shipment from the Order is now with the courier and on its way to your patient. Note that this event may be sent simultaneously with the shipment_created event, the event order is not guaranteed. Tracking information will be included if available.

{
  "type": "shipment_shipped",
  "data": {
    "orderId": "ord_1234567890",
    "shipmentId": "ship_1234567890",
    "shippingService": "DHL Express" | undefined,
    "trackingId": "1234567890" | undefined,
    "trackingUrl": "https://www.dhl.com/en/express/tracking.html?AWB=1234567890" | undefined,
    "estimatedDeliveryDate": "2024-10-10T12:00:00Z" | undefined,
    "orderDownstreamId": "downstream_123" | undefined
  }
}

A Shipment from the Order has been delivered to your patient. This event will only be sent for tracked delivery methods where the courier supports delivery notifications.

{
  "type": "shipment_delivered",
  "data": {
    "orderId": "ord_1234567890",
    "shipmentId": "ship_1234567890",
    "shippingService": "DHL Express",
    "trackingId": "1234567890",
    "trackingUrl": "https://www.dhl.com/en/express/tracking.html?AWB=1234567890",
    "orderDownstreamId": "downstream_123" | undefined
  }
}

A Shipment delivery from the Order was not successful. The reason for the failure will be included in the event's reason property. Tracking information will only be provided for tracked delivery methods where the courier supports delivery notifications.

{
  "type": "shipment_undeliverable",
  "data": {
    "orderId": "ord_1234567890",
    "shipmentId": "ship_1234567890",
    "shippingService": "DHL Express",
    "trackingId": "1234567890",
    "trackingUrl": "https://www.dhl.com/en/express/tracking.html?AWB=1234567890",
    "reason": "Delivery failed 3 times and was returned to the warehouse.",
    "orderDownstreamId": "downstream_123" | undefined
  }
}

Patient scheduled an appointment with a prescriber.

{
  "type": "prescription_request_appointment_created",
  "data": {
    "prescriptionRequestId": "rxreq_1234567890",
    "prescriberName": "John Doe",
    "scheduledDate": "2024-10-10T12:00:00Z",
  }
}

Patient rescheduled an existing appointment.

{
  "type": "prescription_request_appointment_rescheduled",
  "data": {
    "prescriptionRequestId": "rxreq_1234567890",
    "prescriberName": "John Doe",
    "scheduledDate": "2024-10-10T12:00:00Z",
  }
}

Patient cancelled the appointment and can rebook using original schedulinglink from Prescription Request Assigned event.

{
  "type": "prescription_request_appointment_cancelled",
  "data": {
    "prescriptionRequestId": "rxreq_1234567890",
  }
}

Patient did not show up for the appointment and can rebook using original schedulinglink from Prescription Request Assigned event.

{
  "type": "prescription_request_appointment_no_show",
  "data": {
    "prescriptionRequestId": "rxreq_1234567890",
  }
}

The media API allows you to securely upload supporting files that can then be referenced elsewhere in the Foundation Health API. For example a patient may need to provide images as part of an async consultation. These images can be uploaded to the media API and the returned IDs included when submitting a Consultation Response.

The Foundation Health API formats errors according to the JSON API specification.

The generic error response will look like this:

{
  "errors": [
    {
      "code": "error_code",
      "title": "Error Title",
      "detail": "Error detail message.",
      "meta": {}
    }
  ]
}