Flexpa
Talk to us

Guides

  • Overview
  • QuickstartNew
  • Coverage
  • Viewing Medications
  • Explanation of Benefits

SDK

  • Link
  • API

Reference

  • Patient access
  • Endpoints

About

  • ChangelogNew
  • FAQ
  • Join us
  • Brand
  • Privacy Policy

API Reference

Use the API to retrieve claims and clinical data from a linked health plan

Introduction

The Flexpa API is a REST API. Our API functions as an opinionated request proxy layer for FHIR. Every resource available in the API conforms to one available in FHIR.

You can use the Flexpa API in test mode, which doesn't use real patient data. The API key you use to authenticate the request determines whether the request is made in live mode or test mode.

To start using Flexpa API your users must link their health plan with Flexpa Link.

Modes

Flexpa has two environments, or operating modes.

  • Test

    Get started immediately with test patient credentials. API calls return simulated data in test mode. Use this mode as you build your app.

  • Live

    Launch your app with live patient credentials. API calls return real data in Live mode.

Keys

Each app uses one pair of API keys for each environment for a total of four. Each pair consists of a public and secret part.

  • publishable_key

    A unique key to identify your app, may be used on the client-side.

  • secret_key

    A confidential secret that you must not share publicly.

Test Mode Keys

Generate your own set of Test Mode API keys to get started

URL

The base URL for the Flexpa API is https://api.flexpa.com. All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authentication

The Flexpa API uses API keys and Access Tokens to authenticate requests. You obtain a Patient Access Token as the last step of the Flexpa Link auth flow.

Authentication to the per-patient FHIR Resources is performed via bearer auth.

Submit an Authorization header with a value of Bearer ${PAT} where ${PAT} is a currently valid Patient Access Token.

Access Tokens

Link Exchange

POST https://api.flexpa.com/link/exchange

Access Tokens are obtained by exchanging a Flexpa Link public_token for an API access_token.

  • Flexpa Link returns a public_token in the onSuccess callback after a user has successfully linked their health plan.
  • To exchange a public_token for an access_token send an HTTP POST request to https://api.flexpa.com/link/exchange with a Content-Type: application/json header and a JSON body containing the public_token and your secret_key API key.
  • It's important to only call this endpoint from your server, as to not expose your secret_key.

Request fields:

  • public_token - received from the Flexpa Link onSuccess callback
  • secret_key - your Flexpa API secret key.

Response fields:

  • access_token - the access_token to be used to make FHIR requests on behalf of this user
  • patient_id - the FHIR Identifier that uniquely corresponds to this Patient.

Example:

curl -X POST https://api.flexpa.com/link/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "public_token": "public_token_950fae5f-7903-4ce1-9414-9b44c4e55263",
    "secret_key": "<your-secret-key>""
  }'

Introspecting Access Tokens

Access tokens are JWTs that contain the encoded fields:

  • iat - when the token was issued
  • exp - when the token expires
  • sub - the subject of the JWT (a string in the format of "Patient/<patient_id>")

You can decode the JWT either by:

  • using a client side library like jwt-decode
  • Calling Flexpa API's introspect endpoint

Introspect Endpoint

GET https://api.flexpa.com/smart/introspect

Request headers:

  • Authorization - the access_token received from the link exchange endpoint

Response fields:

  • payload - an object containing the iat, exp and sub fields
  • protectedHeader - an object containing the alg field; the algorithm used to sign the JWT

Example:

ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/smart/introspect -H "Authorization: $ACCESS_TOKEN"

FHIR Resources

You can make FHIR resource requests after acquiring an access_token from POST /link/exchange.

Currently supports Read and Search requests. Add the FHIR resource you want to Read or Search after the /fhir/ subpath of the URL.

Example: https://api.flexpa.com/fhir/Patient/123

You can also pass any paramters as you normally would to a FHIR API:

Example: https://api.flexpa.com/fhir/Coverage?patient=Patient/123

Request fields:

  • access_token - Passed in as a header.
    • Authorization: Bearer ${access_token}.

Response fields: The FHIR resource requested, in JSON format.

Coverage

GET https://api.flexpa.com/fhir/Coverage

  • Coverage is a base FHIR Resource
  • Commonly available via the C4BB Coverage Profile.

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/Coverage?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

ExplanationOfBenefit

GET https://api.flexpa.com/fhir/ExplanationOfBenefit

  • ExplanationOfBenefit is a base FHIR Resource ( JSON example)
  • Commonly available via C4BB ExplanationOfBenefit Inpatient Institutional ( JSON example), C4BB ExplanationOfBenefit Outpatient Institutional ( JSON example), C4BB ExplanationOfBenefit Pharmacy ( JSON example), C4BB ExplanationOfBenefit Professional NonClinician ( JSON example)

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/ExplanationOfBenefit?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

MedicationRequest

GET https://api.flexpa.com/fhir/MedicationRequest

  • MedicationRequest is a base FHIR Resource
  • Commonly available via US Core MedicationRequest Profile

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/MedicationRequest?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Procedure

GET https://api.flexpa.com/fhir/Procedure

  • Procedure is a base FHIR Resource
  • Commonly available via US Core Procedure Profile

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/Procedure?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Observation

GET https://api.flexpa.com/fhir/Observation

  • Observation is a base FHIR Resource
  • Commonly available via US Core Vital Signs Profile

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/Observation?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

We can also request Observations(and any other resources) that conform to a specific profile

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123
PROFILE=http://hl7.org/fhir/us/core/StructureDefinition/us-core-vital-signs

curl "$FLEXPA_API/Observation?patient=$PATIENT_ID&_profile=$PROFILE" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Encounter

GET https://api.flexpa.com/fhir/Encounter

  • Encounter is a base FHIR Resource
  • Commonly available via US Core Encounter Profile

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/Encounter?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Condition

GET https://api.flexpa.com/fhir/Condition

  • Condition is a base FHIR Resource ( JSON example)
  • Commonly available via US Core Encounter Profile ( JSON example)

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/Condition?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

CareTeam

GET https://api.flexpa.com/fhir/CareTeam

  • CareTeam is a base FHIR Resource ( JSON example)
  • Commonly available via US Core Encounter Profile

Sample curl

FLEXPA_API=https://api.flexpa.com/fhir
ACCESS_TOKEN=flexpa-link-access-token
PATIENT_ID=Patient/A000123

curl "$FLEXPA_API/CareTeam?patient=$PATIENT_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
On this page
  • Introduction
  • Modes
  • Keys
  • URL
  • Authentication
  • Access Tokens
  • Link Exchange
  • Introspecting Access Tokens
  • Introspect Endpoint
  • FHIR Resources
  • Coverage
  • ExplanationOfBenefit
  • MedicationRequest
  • Procedure
  • Observation
  • Encounter
  • Condition
  • CareTeam
TwitterGitHub

© 2022 Automate Medical, Inc. All rights reserved.