Search documentation... `⌘K`

[Developer Portal](https://portal.flexpa.com/) [Get Sandbox](https://www.flexpa.com/sandbox) [Try it yourself](https://www.flexpa.com/docs/guides/agents)

Open main menu

[**All docs**](https://www.flexpa.com/docs)

## [Records](https://www.flexpa.com/docs/records\#records)

- [How it works](https://www.flexpa.com/docs/records#how-it-works)
- [What you need](https://www.flexpa.com/docs/records#what-you-need)
- [API Keys](https://www.flexpa.com/docs/records#api-keys)
- [Access Tokens](https://www.flexpa.com/docs/records#access-tokens)
- [Patient Access Token](https://www.flexpa.com/docs/records#patient-access-token)
- [Application Access Token](https://www.flexpa.com/docs/records#application-access-token)
- [Patient Authorizations](https://www.flexpa.com/docs/records#patient-authorizations)
- [Request ID](https://www.flexpa.com/docs/records#request-id)
- [Sync Job States](https://www.flexpa.com/docs/records#sync-job-states)

## [FHIR API](https://www.flexpa.com/docs/records\#fhir-api)

- [GETRead](https://www.flexpa.com/docs/records#read)
- [GETSearch](https://www.flexpa.com/docs/records#search)
- [GETPatient $everything](https://www.flexpa.com/docs/records#patient-everything)
- [GETPatient $summary](https://www.flexpa.com/docs/records#patient-summary)
- [POSTPatient $health-cards-issue](https://www.flexpa.com/docs/records#patient-health-cards-issue)
- [POSTPatient $expunge](https://www.flexpa.com/docs/records#patient-expunge)
- [POSTViewDefinition $run](https://www.flexpa.com/docs/records#viewdefinition-run)
- [GETCapability Statement](https://www.flexpa.com/docs/records#capability-statement)
- [Wildcard Parameters](https://www.flexpa.com/docs/records#wildcard-parameters)
- [Search Result Parameters](https://www.flexpa.com/docs/records#search-result-parameters)
- [Pagination](https://www.flexpa.com/docs/records#pagination)
- [Referenced Resources](https://www.flexpa.com/docs/records#referenced-resources)
- [Errors](https://www.flexpa.com/docs/records#errors)

## [Transforms](https://www.flexpa.com/docs/records\#transforms)

- [Code systems](https://www.flexpa.com/docs/records#code-systems)
- [Tags](https://www.flexpa.com/docs/records#tags)
- [Identifiers](https://www.flexpa.com/docs/records#identifiers)
- [References](https://www.flexpa.com/docs/records#references)
- [NPIs](https://www.flexpa.com/docs/records#npis)
- [Medications](https://www.flexpa.com/docs/records#medications)
- [Conditions](https://www.flexpa.com/docs/records#conditions)
- [Validation](https://www.flexpa.com/docs/records#validation)

## [Provider Directory](https://www.flexpa.com/docs/records\#provider-directory)

- [GETPractitioner](https://www.flexpa.com/docs/records#practitioner)
- [GETOrganization](https://www.flexpa.com/docs/records#organization)

## [FAQ](https://www.flexpa.com/docs/records\#faq)

- [POSTApply](https://www.flexpa.com/docs/records#apply)

## [Next steps](https://www.flexpa.com/docs/records\#next-steps)

# FHIR API Reference

## [\#](https://www.flexpa.com/docs/records\#records) Records

The Flexpa API is based on the HL7® FHIR® standard that gives you access to health insurance claims, plan details, and medical records from our [network of payers](https://www.flexpa.com/docs/network/directory).

Every resource available conforms to the FHIR R4 standard.

### [\#](https://www.flexpa.com/docs/records\#how-it-works) How it works

1. Patients consent to transfer health data through [Flexpa Consent](https://www.flexpa.com/docs/consent) to your application
2. Your server exchanges the consent for an access token
3. Use these tokens to make authenticated requests to Flexpa's FHIR API endpoints
4. Receive standardized FHIR-compliant health data that you can use in your application

### [\#](https://www.flexpa.com/docs/records\#what-you-need) What you need

To use the Flexpa API effectively, you'll need:

- A pair of [API Keys](https://www.flexpa.com/docs/guides/quickstart#set-api-keys) ( [talk to our team](https://www.flexpa.com/demo))
- A backend server to securely manage tokens and make API requests
- Understanding of [FHIR](https://www.flexpa.com/docs/fhir/introduction) resources (recommended)

You can use the API in [test mode](https://www.flexpa.com/docs/test-mode) to explore endpoints with sample data before going live with real patient data.

### Base URL

```bash
https://api.flexpa.com
```

CopyCopied!

### Getting started?

[**Quickstart** Get started with a cloneable quickstart project\\
\\
* * *\\
\\
Try it out →](https://www.flexpa.com/docs/guides/quickstart)

### Looking for a demo?

[**Try it yourself** Go through a Patient Access API flow yourself! See exactly what patients will see\\
\\
* * *\\
\\
Try it yourself →](https://my.flexpa.com/connect)

* * *

### [\#](https://www.flexpa.com/docs/records\#api-keys) API Keys

The Flexpa API uses a two-layer authentication system.
API Keys are used for securely identifying your application to Flexpa and for OAuth token requests.

API Keys come in pairs: a **Publishable Key** and a **Secret Key**.

Publishable keys have the prefix `pk_test_` for test mode and `pk_live_` for live mode.
They are used in client-side code, like in the [Consent](https://www.flexpa.com/docs/consent) authorization step.

Secret keys have the prefix `sk_test_` and `pk_live_`. They are used only in server-side code and must be kept secure.

#### API Key Authorization Header

Authorization: Basic ${base64\_encoded\_credentials}

Required for OAuth token requests.

* * *

### [\#](https://www.flexpa.com/docs/records\#access-tokens) Access Tokens

The Flexpa API supports two distinct types of access tokens, each designed for different use cases. Access tokens are [JWTs](https://jwt.io/introduction) that contain claims about the token's identity and permissions.

Both are sent to the API in an `Authorization: Bearer` header.

#### [\#](https://www.flexpa.com/docs/records\#differences) Differences

| If you need to... | Use this token type |
| --- | --- |
| Access a specific patient's data | [Patient Access Token](https://www.flexpa.com/docs/records#patient-access-token) |
| Make application-level API calls without patient context | [Application Access Token](https://www.flexpa.com/docs/records#application-access-token) |
| Access API endpoints like `/fhir/metadata` | Either token type works |

* * *

#### Access Token Authorization Header

Authorization: Bearer eyJhbGc...

Required for all [FHIR API](https://www.flexpa.com/docs/records#fhir-api) requests.

### [\#](https://www.flexpa.com/docs/records\#patient-access-token) Patient Access Token

Patient Access Tokens are created when a patient authorizes your application through [Flexpa Consent](https://www.flexpa.com/docs/consent) and you complete the [exchange](https://www.flexpa.com/docs/consent#exchange) step. These tokens are tied to a specific patient's identity and grant access to that patient's health data.

- Used for accessing patient-specific health records
- Tied to a specific patient identity - all API responses are automatically filtered
- Valid for 24 hours
- Obtained from the [exchange](https://www.flexpa.com/docs/consent#exchange) step
- Can be refreshed with a refresh token for `MULTIPLE` usage authorizations
- You can inspect token details using the [introspect](https://www.flexpa.com/docs/consent#introspect) endpoint

#### JWT claims

jti

A unique identifier for the JWT (JSON Web Token). Generated as a random UUID to identify this specific token.

sub

Subject identifier. Contains the [Consent](https://www.flexpa.com/docs/consent#consent-1) ID.

patient

FHIR Patient resource identifier in the format `Patient/id`. This claim is specific to Patient Access Tokens.

client\_id

OAuth 2.0 client identifier of the application that requested the token.

iat

Time at which the JWT was issued, in seconds since Unix epoch.

exp

Expiration time in seconds since Unix epoch. Patient Access Tokens expire 24 hours after issuance.

iss

Identifies the issuer of the JWT. Always " [https://api.flexpa.com/](https://api.flexpa.com/)".

aud

Identifies the intended audience of the JWT. Always " [https://api.flexpa.com/](https://api.flexpa.com/)".

* * *

### [\#](https://www.flexpa.com/docs/records\#application-access-token) Application Access Token

Application Access Tokens operate at the application level without any patient context. You obtain these through the OAuth 2.0 Client Credentials flow, using your application's API keys.

- Used for accessing application-level resources without patient context
- Valid for 30 minutes
- Obtained through Client Credentials grant flow on the [Token Endpoint](https://www.flexpa.com/docs/consent#token)
- Cannot be refreshed (request a new token when needed)
- Used to access the [Provider Directory](https://www.flexpa.com/docs/records#provider-directory)
- **Live mode keys only**: Application access tokens can only be created using live mode API keys

#### JWT claims

jti

A unique identifier for the JWT (JSON Web Token). Generated as a random UUID to identify this specific token.

sub

Subject identifier. For Application Tokens, this matches the client\_id (application ID).

client\_id

OAuth 2.0 client identifier of the application that requested the token.

iat

Time at which the JWT was issued, in seconds since Unix epoch.

exp

Expiration time in seconds since Unix epoch. Application Access Tokens expire 30 minutes after issuance.

iss

Identifies the issuer of the JWT. Always " [https://api.flexpa.com/](https://api.flexpa.com/)".

aud

Identifies the intended audience of the JWT. Always " [https://api.flexpa.com/](https://api.flexpa.com/)".

* * *

### [\#](https://www.flexpa.com/docs/records\#patient-authorizations) Patient Authorizations

Patient Authorizations are the secure permissions granted by patients to access their health data. These authorizations are what enable the creation of Patient Access Tokens.

A Patient Authorization represents consent from a patient to access their data from a specific health plan or provider. When a patient completes the [Consent](https://www.flexpa.com/docs/consent) flow:

1. They select their health plan or provider
2. They authenticate with that organization
3. They explicitly consent to share specific data with your application
4. Flexpa creates a Patient Authorization that maintains this consent

Patient Authorizations can be configured as either:

- **ONE\_TIME**: A single 24-hour window of access after which the authorization and all associated data are deleted
- **MULTIPLE**: Ongoing access that refreshes regularly without requiring the patient to re-authorize

Each Patient Authorization has a unique lifecycle with different states which you can track via the [introspect](https://www.flexpa.com/docs/consent#introspect) endpoint. When a patient chooses to revoke access, you can use the [revoke](https://www.flexpa.com/docs/consent#revoke) endpoint to delete the authorization and associated data.

#### Authorization states

CREATED

The initial state when a patient authorization record is created but before the authentication process has begun.

AUTHORIZING

The patient is in the process of authenticating with their health plan but has not yet completed the process.

AUTHORIZED

The patient has successfully authenticated with their health plan and granted consent, but the authorization has not yet been exchanged for an access token.

EXCHANGED

The public token has been exchanged for an access token, and the patient's data is being synchronized.

REFRESHED

For MULTIPLE usage authorizations only. The access token has been refreshed at least once using a refresh token.

ERRORED

An error occurred during the authorization or data synchronization process.

ABANDONED

The patient started the authorization process but did not complete it. This could be due to various reasons like timeout, closing the window, or navigation away.

BOUNCED

The authorization process was rejected by the health plan's system, possibly due to invalid credentials or other issues.

REVOKED

The authorization has been explicitly revoked by the patient or your application using the revoke endpoint.

* * *

### [\#](https://www.flexpa.com/docs/records\#request-id) Request ID

Each API request has an associated request identifier.
You can find this value in the response headers, under `X-Request-Id`.
If you need help debugging a request, please include the Request Id when [contacting support](https://www.flexpa.com/docs/support).

* * *

### [\#](https://www.flexpa.com/docs/records\#sync-job-states) Sync Job States

When a patient authorizes access to their health data through [Flexpa Consent](https://www.flexpa.com/docs/consent), a synchronization process is initiated to retrieve and cache their records from the health plan's API. This process is managed through a Sync Job, which allows you to track the status of data retrieval.

Sync Jobs are automatically created after a successful patient authorization and progress through several states as data is retrieved, processed, and made available through the [Flexpa API](https://www.flexpa.com/docs/records).

During the initial sync period (typically less than 1 minute), FHIR API requests may return a 429 status code. Once the sync is complete (status: `COMPLETED`), patient data becomes available for querying. You can monitor the current sync state through the [`sync.state`](https://www.flexpa.com/docs/docs/consent#exchange) property returned in the exchange response or via the [introspect](https://www.flexpa.com/docs/docs/consent#introspect) endpoint.

#### Sync job states

CREATED

The sync job has been created after successful patient authorization. This is its initial state.

WAITING

The sync job is queued for processing and will begin retrieving data from the health plan's API soon.

ACTIVE

The sync job is currently retrieving and processing the patient's health data from their health plan.

FAILED

The sync job encountered an error and was unable to complete. This may require the patient to re-authorize.

COMPLETED

The sync job has successfully retrieved and processed all available patient data, which is now available through the [FHIR API](https://www.flexpa.com/docs/records#fhir-api).

## [\#](https://www.flexpa.com/docs/records\#fhir-api) FHIR API

All FHIR API requests must be made with a [Patient Access Token](https://www.flexpa.com/docs/records#patient-access-token) or an [Application Access Token](https://www.flexpa.com/docs/records#application-access-token) in the Authorization header.

FHIR API routes begin with the `/fhir/` subpath of the URL.
Flexpa's FHIR API is designed to provide a consistent, reliable, and developer-friendly experience when working with health data. Our architecture offers several key benefits:

- **Consistent API Experience**: We normalize the behavior of FHIR operations across all payers, providing uniform support for features like [Patient $everything](https://www.flexpa.com/docs/fhir/introduction#patient-everything-operation).

- **Enhanced Search Capabilities**: Flexpa supports comprehensive search functionality, including consistent implementation of parameters like `patient` and powerful features like `_include` across all data sources.

- **Standardized Data Model**: We dynamically adapt to the unique implementations of each payer's FHIR API and transform the data to provide a consistent experience, including:
  - Creating MedicationRequest resources from pharmacy claim data in ExplanationOfBenefit resources ( [learn more](https://www.flexpa.com/docs/fhir/medication-request#flexpa-enhancements))
  - Generating US Core clinical resources (Encounter, Condition, Procedure) from claims data ( [learn more](https://www.flexpa.com/docs/records/claims-to-clinical))
  - Normalizing code systems and adding human-readable display values
  - Enhancing resource references for better data connectivity
  - Filling in missing information where available from other sources

Explore these powerful features to enhance your development experience:

- [Wildcard Parameters](https://www.flexpa.com/docs/records#wildcard-parameters)
- [Search Result Parameters](https://www.flexpa.com/docs/records#search-result-parameters)
- [Pagination](https://www.flexpa.com/docs/records#pagination)
- [Referenced Resources](https://www.flexpa.com/docs/records#referenced-resources)
- [Code Systems](https://www.flexpa.com/docs/records#/docs/fhir/code-systems)
- [Errors](https://www.flexpa.com/docs/records#errors)

[**Intro to FHIR** FHIR, or Fast Healthcare Interoperability Resources, is a standard for exchanging healthcare information electronically\\
\\
* * *\\
\\
Read introduction →](https://www.flexpa.com/docs/fhir/introduction)

[**FHIR R4 Standard** Flexpa implements the FHIR R4 specification, the industry standard for healthcare interoperability\\
\\
* * *\\
\\
View FHIR R4 Documentation →](https://hl7.org/fhir/R4/)

* * *

GEThttps://api.flexpa.com/fhir/\[Resource\]/:id

### [\#](https://www.flexpa.com/docs/records\#read) Read

A read is the most basic operation in FHIR. It allows you to retrieve the current version of a single resource by its ID.

For a full list of available Resources, please refer to the [FHIR Resources documentation](https://www.flexpa.com/docs/fhir/introduction).

Many resources returned by the API will contain references to other resources.
For more information on how to handle references, see the [Referenced Resources](https://www.flexpa.com/docs/records#referenced-resources) section.

#### Request headers

AuthorizationstringRequired

An `Authorization: Bearer` header value must presented with a [Patient Access Token](https://www.flexpa.com/docs/records#patient-access-token) or an [Application Access Token](https://www.flexpa.com/docs/records#application-access-token)

#### Request parameters

identifierstring

The identifier of the resource to be retrieved - used in the last part of the URL path segment

#### Response fields

resourceTypestring

Reads return an individual resource, so the resource type is expected to correspond to the resource you are reading

#### Error codes

transient429 status code

The API is expected to return a 429 status code until the data is ready to be retrieved.
This error is returned by the API while in the [initial sync period](https://flexpa.com/docs/consent#sync), which typically lasts less than 1 minute.

You will need to implement retry logic to handle this error. If you are using the [Node SDK](https://flexpa.com/docs/records/node-sdk) which we demonstrate in our [Quickstart guide](https://www.flexpa.com/docs/guides/quickstart), retry logic is already built in and you don't need to implement it yourself.

processing422 status codeThe API is expected to return a 422 when Flexpa fails to synchronize any resources from the Endpoint for the requested Patient. Please re-authorize or reach out to support.

### Request

cURLJavaScript

GET

/fhir/\[Resource\]

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Coverage/123 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

CopyCopied!

### Response

```json
{
  "resourceType": "Coverage",
  "id": "123"
}
```

CopyCopied!

* * *

GEThttps://api.flexpa.com/fhir/\[Resource\]

### [\#](https://www.flexpa.com/docs/records\#search) Search

Searches on Flexpa API follow the RESTful style of the FHIR specification by submitting a GET HTTP request to the base URL of the resource with parameters to define the exact search criteria to filter the response.

#### Request headers

AuthorizationstringRequired

#### Request parameters

\_includestring

The referenced resources to include in the search response.
Only applies to [relative references](https://www.flexpa.com/docs/records#relative-references).
The value of the `searchInclude` parameter has the format `[Resource]:[field]`, for example `Patient:general-practitioner`.
For more information on available `searchInclude` parameters, please refer to the [CapabilityStatement](https://www.flexpa.com/docs/records#search-include).

\_revincludestring

Like `_include` but intstead of including the resources referenced within the searched-for resource, include resources that may _reference_ the searched resource.
The value of the `searchRevInclude` parameter has the format `[Resource]:[field]`, for example `Provenance:target`.

\[searchParam\]string

To filter the search results server-side, you can use any of the available search parameters for the resource type you are searching for.
For more information on available `searchParam` parameters, please refer to the [CapabilityStatement](https://www.flexpa.com/docs/records#search-param).

Search results can also be modified by certain search result parameters.
For more information on available search result parameters, see the [Search Result Parameters](https://www.flexpa.com/docs/records#search-result-parameters) section.

#### Response fields

resourceTypestring

Searches return a `Bundle` resource type

entryarray

An array of FHIR resources expected to match the resource type of the search

#### Error codes

transient429 status code

processing422 status codeThe API is expected to return a 422 when Flexpa fails to synchronize any resources from the Endpoint for the requested Patient. Please refresh again or reach out to support.

### Request

cURLSearchwith \_includewith filter

GET

/fhir/\[Resource\]

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/ExplanationOfBenefit \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

CopyCopied!

### Response

Searchwith \_includewith filter

```json
{
  "resourceType": "Bundle",
  "id": "22f61d0877b54b2a8a2feb57bfe2c462",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "123"\
      }\
    },\
    {\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "456"\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

GEThttps://api.flexpa.com/fhir/Patient/$PATIENT\_ID/$everything

### [\#](https://www.flexpa.com/docs/records\#patient-everything) Patient $everything

Unique to the Patient resource, the [Patient $everything](https://hl7.org/fhir/R4/operation-patient-everything.html) returns all [patient-compartmentalized](https://hl7.org/fhir/R4/compartmentdefinition-patient.html) resources, as well as any Organization, Location, Practitioner, and Medication resources that are present in the patient's FHIR data.

You will need to make additional [search](https://www.flexpa.com/docs/records#search) requests for any non-patient compartmentalized resources, for example:

- [Location](https://www.flexpa.com/docs/fhir/location)
- [Device](https://www.flexpa.com/docs/fhir/device)
- [PractitionerRole](https://www.flexpa.com/docs/fhir/practitioner-role)

This request returns large Bundles. The client should be prepared to handle a potentially large single response.

#### Request headers

AuthorizationstringRequired

An `Authorization: Bearer` header value must be presented with a [Patient Access Token](https://www.flexpa.com/docs/records#patient-access-token) when using a wildcard `$PATIENT_ID` or otherwise an [Application Access Token](https://www.flexpa.com/docs/records#application-access-token)

#### Response fields

ResponseBundle

Patient $everything returns a Bundle that contains all resources that reference the Patient resource.

### Request

cURLJavaScript

GET

/fhir/Patient/$PATIENT\_ID/$everything

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$everything' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

CopyCopied!

### Response

```json
{
  "resourceType": "Bundle",
  "entry": [\
    { "resource": {"resourceType": "Patient", ...} },\
    { "resource": {"resourceType": "Coverage", ...} },\
    { "resource": {"resourceType": "ExplanationOfBenefit", ...} },\
  ]
}
```

CopyCopied!

This example makes use of the `$PATIENT_ID` [wildcard parameter](https://www.flexpa.com/docs/records#wildcard-parameters) which requires a [Patient Access Token](https://www.flexpa.com/docs/records#patient-access-token).
When using with an [Application Access Token](https://www.flexpa.com/docs/records#application-access-token), replace the wildcard parameter with a specific Patient ID.

* * *

GEThttps://api.flexpa.com/fhir/Patient/$PATIENT\_ID/$summary

### [\#](https://www.flexpa.com/docs/records\#patient-summary) Patient $summary

The `$summary` operation generates an [International Patient Summary (IPS)](https://hl7.org/fhir/uv/ips/) document for the patient. The IPS is a standards-based clinical summary designed for unscheduled or cross-border care, returning a FHIR Bundle of type `document` with a [Composition](https://hl7.org/fhir/R4/composition.html) resource that organizes the patient's key health information into 14 standardized sections.

The generated IPS document includes:

- **PDF rendering** — a [DocumentReference](https://www.flexpa.com/docs/fhir/document-reference) containing a rendered PDF of the patient summary is automatically included in the Bundle, suitable for display in systems that do not support FHIR
- **Status-based filtering** — only clinically relevant resources (e.g., active medications, completed immunizations, final lab results)
- **Section narratives** — each section contains a human-readable XHTML table
- **Empty section handling** — sections with no data include `emptyReason` of `unavailable`; sections excluded via `_section` include `emptyReason` of `withheld`
- **Confidentiality tagging** — the Bundle carries a `meta.security` high water mark reflecting the most restrictive confidentiality code across included resources

Use the `_section` query parameter to restrict which IPS sections appear in the summary. This is useful when patients want to share only specific categories of health data — for example, sharing allergies and medications with a new provider but withholding social history. Values can be LOINC section codes or short aliases. When `_section` is omitted, all available sections are returned.

| Alias | LOINC code | Section |
| --- | --- | --- |
| `allergies` | 48765-2 | Allergies |
| `medications` | 10160-0 | Medications |
| `problems` | 11450-4 | Problem list |
| `immunizations` | 11369-6 | Immunizations |
| `procedures` | 47519-4 | Procedures |
| `results` | 30954-2 | Results |
| `vitalsigns` | 8716-3 | Vital signs |
| `socialhistory` | 29762-2 | Social history |
| `devices` | 46264-8 | Devices |
| `planofcare` | 18776-5 | Plan of treatment |
| `functionalstatus` | 47420-5 | Functional status |
| `pastillness` | 11348-0 | History of past illness |
| `pregnancy` | 10162-6 | Pregnancy history |
| `advancedirectives` | 42348-3 | Advance directives |

The IPS is more compact than `$everything` — it returns a curated clinical summary rather than the full patient compartment. Use `$everything` when you need all available data, and `$summary` when you need a structured clinical overview. When `_section` is provided, excluded sections remain in the Composition (preserving the IPS structure) but contain no entries and are marked as `withheld`. Only resources referenced by included sections are present in the Bundle. Patient, Composition, and author resources are always retained.

#### Request headers

AuthorizationstringRequired

#### Request query parameters

\_sectionstring

One or more LOINC section codes or aliases to include. Repeat for multiple sections. When omitted, all sections are returned.

#### Response fields

ResponseBundle

A Bundle of type `document` containing a Composition resource, referenced clinical resources organized into IPS sections, and a DocumentReference with a rendered PDF of the summary. The Composition always includes all 14 sections — sections with data contain `entry` references; sections without data or excluded by `_section` contain an `emptyReason`.

### Request

cURLJavaScript

GET

/fhir/Patient/$PATIENT\_ID/$summary

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$summary' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

CopyCopied!

### Filtered request

cURLJavaScript

GET

/fhir/Patient/$PATIENT\_ID/$summary?\_section=...

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$summary?_section=allergies&_section=medications' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

CopyCopied!

### Response

```json
{
  "resourceType": "Bundle",
  "type": "document",
  "timestamp": "2026-02-19T00:00:00.000Z",
  "meta": {
    "security": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality", "code": "N" }]
  },
  "entry": [\
    {\
      "resource": {\
        "resourceType": "Composition",\
        "title": "International Patient Summary",\
        "type": { "coding": [{ "system": "http://loinc.org", "code": "60591-5" }] },\
        "section": [\
          {\
            "title": "Allergies",\
            "code": { "coding": [{ "system": "http://loinc.org", "code": "48765-2" }] },\
            "entry": [{ "reference": "AllergyIntolerance/allergy-1" }]\
          },\
          {\
            "title": "Medications",\
            "code": { "coding": [{ "system": "http://loinc.org", "code": "10160-0" }] },\
            "entry": [{ "reference": "MedicationRequest/med-1" }]\
          },\
          {\
            "title": "Vital Signs",\
            "code": { "coding": [{ "system": "http://loinc.org", "code": "8716-3" }] },\
            "emptyReason": {\
              "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/list-empty-reason", "code": "unavailable" }]\
            }\
          }\
        ]\
      }\
    },\
    { "resource": { "resourceType": "Patient", "..." : "..." } },\
    { "resource": { "resourceType": "Organization", "..." : "..." } },\
    { "resource": { "resourceType": "AllergyIntolerance", "..." : "..." } },\
    { "resource": { "resourceType": "MedicationRequest", "..." : "..." } },\
    {\
      "resource": {\
        "resourceType": "DocumentReference",\
        "status": "current",\
        "type": { "coding": [{ "system": "http://loinc.org", "code": "60591-5", "display": "Patient summary Document" }] },\
        "content": [{ "attachment": { "contentType": "application/pdf", "data": "base64..." } }]\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

POSThttps://api.flexpa.com/fhir/Patient/:id/$health-cards-issue

### [\#](https://www.flexpa.com/docs/records\#patient-health-cards-issue) Patient $health-cards-issue

The `$health-cards-issue` operation creates a SMART Health Card containing the patient's health data as a verifiable credential. This operation generates a digitally signed JWT that packages the patient's FHIR data according to the [SMART Health Cards specification](https://spec.smarthealth.cards/).

The operation always uses the patient's complete data set (equivalent to Patient/$everything), ensuring comprehensive health information is included in the credential.

The health card is returned as a signed JWT string within a Parameters resource, not as a raw SMART Health Card file. The JWT can be converted to a QR code or shared directly as a verifiable credential.

#### Request headers

Authorizationstring

An `Authorization: Bearer` header value must be presented with a [Patient Access Token](https://www.flexpa.com/records#patient-access-token)

#### Request path parameters

idstring

The identifier of the patient - use `$PATIENT_ID` to automatically reference the authenticated patient

#### Request body

resourceTypestring

Must be `Parameters`

parameterarray

Array containing exactly one parameter object

namestring

Must be `credentialType`

valueUristring

Must be `Patient/$everything` (currently the only supported credential type)

#### Response fields

ResponseParameters

Returns FHIR Parameters resource containing the SMART Health Card

parameterarray

Array containing exactly one parameter object

namestring

Will be `verifiableCredential`

valueStringstring

The signed SMART Health Card as a JWT string

### Request

cURLJavaScript

POST

/fhir/Patient/:id/$health-cards-issue

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$health-cards-issue' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "resourceType": "Parameters",
    "parameter": [\
      {\
        "name": "credentialType",\
        "valueUri": "Patient/$everything"\
      }\
    ]
  }'
```

CopyCopied!

### Request Body

```json
{
  "resourceType": "Parameters",
  "parameter": [\
    {\
      "name": "credentialType",\
      "valueUri": "Patient/$everything"\
    }\
  ]
}
```

CopyCopied!

### Response

```json
{
  "resourceType": "Parameters",
  "parameter": [\
    {\
      "name": "verifiableCredential",\
      "valueString": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjNLZmRnLVh3UC03Z..."\
    }\
  ]
}
```

CopyCopied!

* * *

POSThttps://api.flexpa.com/fhir/Patient/:patientId/$expunge

### [\#](https://www.flexpa.com/docs/records\#patient-expunge) Patient $expunge

The `$expunge` operation deletes all resources in a specific Patient resource [compartment](https://hl7.org/fhir/R4/compartmentdefinition.html).
This operation performs a "hard" delete, meaning all data, including resource history, is permanently removed from the server.

Once the data is deleted, any subsequent FHIR requests to retrieve the data will return a 404 status code.

#### Request headers

AuthorizationstringRequired

An `Authorization: Bearer` header value must be presented with a [Patient Access Token](https://www.flexpa.com/docs/records#patient-access-token)

#### Request parameters

patientIdstring

The ID of the patient whose data you want to delete.
This ID must match the patient ID of the access token and can be retrieved with a [search](https://www.flexpa.com/docs/records#search) request for the Patient resource.
There is an option to use the [patient wildcard parameter](https://www.flexpa.com/docs/records#wildcard-parameters) to automatically match the patient ID in the access token.

#### Response fields

ResponseBundle

The Patient $expunge operation returns an OperationOutcome resource, indicating the success or failure of the expunge request.

#### Error codes

transient429 status code

The API is expected to return a 429 status code until the data is ready to be retrieved.
The API returns this error during the [initial sync period](https://flexpa.com/docs/consent#sync), which typically lasts less than 1 minute.

Data cannot be expunged until the initial sync period has passed.

### Request

cURLJavaScript

POST

/fhir/Patient/$PATIENT\_ID/$expunge

```bash
ACCESS_TOKEN=flexpa-link-access-token
curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID/$expunge' \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -X POST
```

CopyCopied!

### Response

```json
{
  "resourceType": "OperationOutcome",
  "id": "accepted",
  "issue": [\
    {\
      "severity": "information",\
      "code": "informational",\
      "details": {\
        "text": "Accepted"\
      },\
      "diagnostics": "http://medplum.flexpa.com/fhir/R4/job/15c72fcc-267e-4372-a85e-26fa20b01634/status"\
    }\
  ],
  "extension": [\
    {\
      "url": "https://medplum.com/fhir/StructureDefinition/tracing",\
      "extension": [\
        {\
          "url": "requestId",\
          "valueUuid": "175885a0-d396-4d1d-9c9d-a618f06cfdc8"\
        },\
        {\
          "url": "traceId",\
          "valueUuid": "5e18c528-a74a-4dac-9cec-b35a2ce33c3e"\
        }\
      ]\
    }\
  ]
}
```

CopyCopied!

* * *

POSThttps://api.flexpa.com/fhir/ViewDefinition/$run

### [\#](https://www.flexpa.com/docs/records\#viewdefinition-run) ViewDefinition $run

The ViewDefinition $run operation does the heavy lifting of parsing FHIR data for you. Define the data your application needs, and get it back as JSON or CSV that's ready to use.

**When to use this:**

- You need specific fields from ExplanationOfBenefit, Patient, or other resources
- You want data in a format that more closely matches your backend systems and is easier to work with
- You don't want to deal with storing or processing FHIR, you just want directly actionable healthcare data

The operation accepts a [ViewDefinition](https://build.fhir.org/ig/FHIR/sql-on-fhir-v2/StructureDefinition-ViewDefinition.html) resource that specifies what to extract, then queries the data and returns the structured response.

**Need help getting started?** We're FHIR experts and can help you craft a ViewDefinition that extracts exactly the data you need. Reach out to your Flexpa contact or our support team.

### Request

```bash
curl -X POST "https://api.flexpa.com/fhir/ViewDefinition/\$run" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Parameters",
    "parameter": [\
      {\
        "name": "viewResource",\
        "resource": {\
          "resourceType": "ViewDefinition",\
          "name": "patient_basics",\
          "status": "active",\
          "resource": "Patient",\
          "select": [{\
            "column": [\
              { "name": "id", "path": "id" },\
              { "name": "family_name", "path": "name.first().family" },\
              { "name": "given_name", "path": "name.first().given.first()" },\
              { "name": "birth_date", "path": "birthDate" }\
            ]\
          }]\
        }\
      }\
    ]
  }'
```

CopyCopied!

#### [\#](https://www.flexpa.com/docs/records\#request-body) Request body

The request body is a FHIR [Parameters](https://hl7.org/fhir/R4/parameters.html) resource containing the operation parameters.

viewResourceViewDefinitionRequired

The ViewDefinition resource specifying what fields to extract. Must be provided inline (not by reference).

patientReference

Optional. Filter results to a specific patient (e.g., `Patient/123`). Primarily for use with Application Access Tokens.

groupReference\[\]

Optional. Filter results to patients in one or more Groups. Can be repeated. Not supported for patient-scoped tokens.

\_formatcode

Output format: `json` (default) or `csv`.

\_limitinteger

Maximum number of output rows to return.

\_sinceinstant

Filter to resources updated since this timestamp.

headerboolean

For CSV output, whether to include the header row. Defaults to `true`.

#### [\#](https://www.flexpa.com/docs/records\#query-parameters) Query parameters

\_countstring

Number of source resources to process per page.

\_offsetstring

Pagination offset for source resources.

#### [\#](https://www.flexpa.com/docs/records\#response) Response

**JSON response** (default):

Returns an object with `rows` (array of extracted data), optional `link` (pagination), and `resourceCount` (number of source resources processed).

**CSV response** (`_format=csv`):

Returns plain CSV text. Pagination info is in response headers:

- `Link`: RFC 5988 format with `rel="next"`
- `X-Next-Link`: Direct URL to next page
- `X-Resource-Count`: Number of source resources

### Response

JSONCSV

```json
{
  "rows": [\
    {\
      "id": "a85f4c92-...",\
      "family_name": "Smith",\
      "given_name": "John",\
      "birth_date": "1985-03-15"\
    }\
  ],
  "resourceCount": 1
}
```

CopyCopied!

For complete ViewDefinition syntax and FHIRPath expressions, see our [Parsing FHIR guide](https://www.flexpa.com/docs/guides/parsing-fhir).

* * *

GEThttps://api.flexpa.com/fhir/metadata

### [\#](https://www.flexpa.com/docs/records\#capability-statement) Capability Statement

CapabilityStatement is a conformance FHIR Resource that is used to understand the exact capabilities that a FHIR server makes available.
The CapabilityStatement resource is used to describe the features and capabilities of a FHIR server in a machine-readable way.
[CapabilityStatement](https://www.hl7.org/fhir/CapabilityStatement.html) is a base FHIR resource.

Flexpa's CapabilityStatement is available at the `/fhir/metadata` route.
View it [here](https://api.flexpa.com/fhir/metadata).

[https://api.flexpa.com/fhir/metadata](https://api.flexpa.com/fhir/metadata) is an unauthenticated route. You do not need to provide an `access_token` to access this route.

#### [\#](https://www.flexpa.com/docs/records\#helpful-capabilities) Helpful capabilities

We've highlighted the following capabilities to provide extra convenience to developers when querying data.
The following examples are defined per-resource.

- [`interaction`](https://www.flexpa.com/docs/records#interaction) is an array of objects that describe the valid operations that can be performed on the resource.
- [`searchInclude`](https://www.flexpa.com/docs/records#search-include) is an array of strings that describe the valid values that can be used with the `_include` search param.
- [`searchParam`](https://www.flexpa.com/docs/records#search-param) is an array of objects that describe the valid params that the server accepts in a URL query string.

### Request

cURLJavaScript

GET

/fhir/metadata

```bash
curl https://api.flexpa.com/fhir/metadata
```

CopyCopied!

### Response

```json
{
  "resourceType": "CapabilityStatement",
  "url": "https://api.flexpa.com/fhir/metadata",
  "title": "Flexpa Capability Statement",
  "date": "2023-11-01",
  "publisher": "Flexpa",
  "rest": [\
    {\
      "mode": "server",\
      "resource": [\
        { "type": "Patient", ... },\
        { "type": "Coverage", ... },\
        { "type": "ExplanationOfBenefit", ... },\
        ...\
      ]\
    }\
  ]
}
```

CopyCopied!

#### [\#](https://www.flexpa.com/docs/records\#interaction) Interaction

All the FHIR resources that Flexpa supports have both a `read` and `search-type` operation, which means that they can be both [read](https://www.flexpa.com/docs/records#read) and [searched](https://www.flexpa.com/docs/records#search).
You can find the `interaction` array in the CapabilityStatement resource.

### Interaction

```json
{
  "resourceType": "CapabilityStatement",
  "url": "https://api.flexpa.com/fhir/metadata",
  "rest": [\
    {\
      "mode": "server",\
      "resource": [\
        {\
          "type": "Practitioner",\
          "interaction": [\
            {\
              "code": "read",\
            },\
            {\
              "code": "search-type",\
            }\
          ]\
        }\
      ]\
    }\
  ]
}
```

CopyCopied!

#### [\#](https://www.flexpa.com/docs/records\#search-include) Search Include

The `searchInclude` array describes the valid values that can be used with the `_include` search param.
Each value is a string with the format `[Resource]:[field]`, where `[Resource]` is the resource type and `[field]` is the field name.
For example, to include the `care-team` field of an [ExplanationOfBenefit](https://www.flexpa.com/docs/fhir/explanation-of-benefit) resource in the search response, you would use the value `ExplanationOfBenefit:care-team`.

For the search to successfully return a [CareTeam](https://www.flexpa.com/docs/fhir/care-team) resource, the following conditions must be met:

1. A `care-team` field must be present in the [ExplanationOfBenefit](https://www.flexpa.com/docs/fhir/explanation-of-benefit) resource.
2. The `care-team` field must contain a [relative reference](https://www.flexpa.com/docs/records#relative-references) to a [CareTeam](https://www.flexpa.com/docs/fhir/care-team) resource.

To use the `_include` search param, refer to the [Search](https://www.flexpa.com/docs/records#search) section.

### Search Include

```json
{
  "resourceType": "CapabilityStatement",
  "url": "https://api.flexpa.com/fhir/metadata",
  "rest": [\
    {\
      "mode": "server",\
      "resource": [\
        {\
          "type": "ExplanationOfBenefit",\
          "searchInclude": [\
            "ExplanationOfBenefit:care-team",\
          ]\
        }\
      ]\
    }\
  ]
}
```

CopyCopied!

#### [\#](https://www.flexpa.com/docs/records\#search-param) Search Param

The `searchParam` array describes the valid params that the server accepts in a URL query string.
These params can be used to filter the search results.
The name of the param can be accessed in the `name` property of each `searchParam` object in the CapabilityStatement resource.

To filter search results with a `searchParam`, refer to the [Search](https://www.flexpa.com/docs/records#search) section.

### Search Param

```json
{
  "resourceType": "CapabilityStatement",
  "url": "https://api.flexpa.com/fhir/metadata",
  "rest": [\
    {\
      "mode": "server",\
      "resource": [\
        {\
          "type": "Condition",\
          "searchParam": [\
            {\
              "name": "onset-age",\
              "definition": "http://hl7.org/fhir/SearchParameter/Condition-onset-age",\
              "type": "quantity"\
            }\
          ]\
        }\
      ]\
    }\
  ]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#wildcard-parameters) Wildcard Parameters

Flexpa API supports wildcard parameters that can be used in URL query parameters in FHIR API requests.

Wildcards are used as tokens directly in the URL of the API request you make to Flexpa.
They are replaced with real values by the API using context provided by the required [Patient Access Token](https://www.flexpa.com/docs/records#authentication).

We currently support one parameter `$PATIENT_ID`, which references the `patient_id` belonging to the `access_token`.
Flexpa will replace this token with the correct `patient_id` when you make an API request to Flexpa.

### Wildcard in Patient Read

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl 'https://api.flexpa.com/fhir/Patient/$PATIENT_ID' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#search-result-parameters) Search Result Parameters

Flexpa supports search result parameters as a way to modify search results. The following search result query parameters can be used in your [search](https://www.flexpa.com/docs/records#search) request:

\_totalstring

The `_total` query parameter will include in the bundle the number of resources that match the search parameters. It is not always visible on the bundle. The possible values for the `_total` search result paramter are:

- `none`: Flexpa will not include the total in the response
- `accurate`: Flexpa will provide the exact total of matching resources, if available. Note that this may be more server intensive.
- `estimate`: Flexpa will provide a rough estimate of the number of matching resources, if available.

\_sortstring

The `_sort` parameter is used to sort results in priority order based on a comma-separated list of search parameters, for example `status,-date,category`.
If the `_sort` value starts with `-`, then the results are returned in decreasing order, otherwise they are returned in increasing order.

\_summarystring

The `_summary` parameter returns a portion of a resource's elements in order to help optimize queries for only the essential information.
Supported values for `_summary` are `true`, which returns only elements that are marked `summary` in the resource's definition, and `count` which will return only the count of matching resources, but no other resource details.

\_elementsstring

The `_elements` parameter returns a specified subset of a resource's elements. Specified elements are given as a list of comma separated values, for example `_elements=identifier,active,link`.
However, _more_ than only requested elements may be returned, including mandatory elements or modifier elements that have values.

\_countstring

The `_count` parameter limits the number of results per page. See [Pagination](https://www.flexpa.com/docs/records#pagination) for more information.

### Request

with \_totalwith \_sortwith \_summarywith \_elements

GET

/fhir/\[Resource\]?\_total=\[none\|accurate\|estimate\]

```js
const ACCESS_TOKEN="flexpa-link-access-token";

const searchUrl = "https://api.flexpa.com/fhir/ExplanationOfBenefit?patient=$PATIENT_ID&_total=accurate";

const response = await fetch(searchUrl, {
  headers: {
    "authorization": `Bearer ${ACCESS_TOKEN}`,
  },
});
const searchBundle = await response.json();
```

CopyCopied!

### Response

with \_totalwith \_sortwith \_summarywith \_elements

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [...],
  "total": 11,
  "link": [...]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#pagination) Pagination

Flexpa supports pagination on the results of a FHIR [search](https://www.flexpa.com/docs/records#search) request.
Pagination can reduce the load on both the client and server.

You can leverage pagination using the following query parameters in your [search](https://www.flexpa.com/docs/records#search) request:

- `_count` to control the page size
- `_offset` to control the page number

In the Flexpa API, the default page size is 20, and the maximum allowed page size is 1000.

Alternatively, if a search result is paginated, the Bundle includes a [`link`](https://www.hl7.org/fhir/http.html#paging) array that references other pages in relation to the current page:

- `self` is the URL of the current page. Always present in `link`.
- `first` is the URL of the first page. Always present in `link`.
- `next` is the URL of the next page. Only present in `link` if there is a next page.
- `previous` is the URL of the previous page. Only present in `link` if there is a previous page.

For example, to access the next page of resources, make a GET request to the URL indicated by `"relation": "next"`.

### Request

cURLJavaScript

GET

/fhir/Condition?\_count=3

```bash
ACCESS_TOKEN=flexpa-link-access-token

curl https://api.flexpa.com/fhir/Condition?_count=3 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

CopyCopied!

### Response

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [ ... ],
  "link": [\
    {\
        "relation": "self",\
        "url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=6&_tag=..."\
    },\
    {\
        "relation": "first",\
        "url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=0&_tag=..."\
    },\
    {\
        "relation": "next",\
        "url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=9&_tag=..."\
    },\
    {\
        "relation": "previous",\
        "url": "https://api.flexpa.com/fhir/Condition?_count=3&_offset=3&_tag=..."\
    },\
  ]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#referenced-resources) Referenced Resources

Many resources returned by the API will contain references to other resources.
A reference is a string that points to the location where the referenced resource can be retrieved.
For instance, a [Patient](https://www.flexpa.com/docs/fhir/patient) may contain a reference to an [Organization](https://www.flexpa.com/docs/fhir/organization) or a [Practitioner](https://www.flexpa.com/docs/fhir/practitioner).

References can be categorized into one of three types, each of which require a different approach to resolve:

- [Relative](https://www.flexpa.com/docs/records#relative-references)
- [Internal](https://www.flexpa.com/docs/records#internal-references)
- [Absolute](https://www.flexpa.com/docs/records#absolute-references)

#### [\#](https://www.flexpa.com/docs/records\#relative-references) Relative references

Relative references are relative to the base resource.
They can be identified by the structure `[resourceType]/[id]`.
You can resolve a relative reference by appending the value of the `reference` string to the base URL in a subsequent GET request.

Alternatively, you can conveniently resolve relative references in a single API request by using the `_include` parameter on a [Search](https://www.flexpa.com/docs/records#search) operation.
For more information on available `searchInclude` parameters, please refer to the [CapabilityStatement](https://www.flexpa.com/docs/records#search-include).

#### [\#](https://www.flexpa.com/docs/records\#internal-references) Internal references

Internal references point to a "contained" resource that is directly embedded within the base resource.
They can be identified by a `#` prefix.
You can access the contained resource in the `contained` field by filtering for the matching `id`.

Contained resources in FHIR do not need to be complete resources.
For example, a contained resource may only contain a `name` field and this is considered valid FHIR.

#### [\#](https://www.flexpa.com/docs/records\#absolute-references) Absolute references

Absolute references are standalone URLs.
They can be identified by any valid URI prefix, but are typically prefixed by either `http`, `https` or `urn`.
You _may_ be able request more data using the URL in its entirety.
Note that this request will be to a FHIR API separate from Flexpa's.

Following URLs to external servers is always risky.
Please consider the security implications of doing so and take the appropriate steps to mitigate unintended access to malicious servers, such as an allowlist of trusted servers for example.
Alternatively, the most conservative approach is to avoid following absolute references altogether.

For more information on references in FHIR, please refer to the [FHIR References documentation](https://hl7.org/fhir/R4/references.html).

### Resolving References

RelativeInternalAbsolute

GET

/fhir/\[Resource\]/:id

```js
const patient = {
  "resourceType" : "Patient",
  "generalPractitioner" : {
    "reference" : "Practitioner/123"
  }
};

const ACCESS_TOKEN="flexpa-link-access-token";

const response = await fetch("https://api.flexpa.com/fhir/Practitioner/123", {
  headers: {
    "authorization": `Bearer ${ACCESS_TOKEN}`,
  },
});
const practitioner = await response.json();
```

CopyCopied!

### Resolved Resource

RelativeInternalAbsolute

```js
{
  "resourceType" : "Practitioner",
  "id" : "123",
  "name" : "Dr. Adam Smith"
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#errors) Errors

When a request is unsuccessful, Flexpa API attempts to return an `OperationOutcome` FHIR R4 Resource.
If the [Endpoint](https://www.flexpa.com/docs/network/directory) connected by the patient during authorization returns an `OperationOutcome` Flexpa API returns it directly.
If the endpoint does not return an `OperationOutcome`, Flexpa API substitutes the actual response with a Flexpa-generated `OperationOutcome` to represent the error.

Your application code should be prepared to handle the following `issue.code` values:

#### Error codes

processing422 status codeProcessing issues. This is expected to be final (e.g., there is no point resubmitting the same content unchanged).

transient429 status codeThe API returns a 429 status code while syncing data from the payer. This happens during the initial sync period, typically lasting less than 1 minute. During this time, data cannot be expunged.

not-supported404 status codeThe interaction, operation, resource or profile is not supported.

forbidden403 status codeThe user does not have the rights to perform this action.

exception500+ status codeAn unexpected internal error has occurred.

### Error response

```json
{
  "resourceType": "OperationOutcome",
  "issue": [{\
    "severity": "error",\
    "code": "not-supported"\
  }],
};
```

CopyCopied!

* * *

## [\#](https://www.flexpa.com/docs/records\#transforms) Transforms

Flexpa's transform pipeline automatically enhances FHIR data received from payers, delivering a more consistent, comprehensive, and usable dataset. These transforms are applied to all data retrieved through the Flexpa API without any configuration needed.

Our transform architecture offers several key benefits:

- **Consistent Resource Structure**: Normalized formats across all payers, enabling you to build once and support all health plans

- **Enhanced Provider Information**: Automatically enriched resources with detailed provider data through NPI resolution

- **Standardized Identifiers**: Deterministic UUIDv5 identifiers ensuring consistent identification and preventing collisions

- **Improved Reference Integrity**: Standardized references between resources for easier data navigation

The sections below highlight the most significant transforms in our pipeline:

- [Code systems](https://www.flexpa.com/docs/records#code-systems)
- [Tags](https://www.flexpa.com/docs/records#tags)
- [Identifiers](https://www.flexpa.com/docs/records#identifiers)
- [References](https://www.flexpa.com/docs/records#references)
- [NPIs](https://www.flexpa.com/docs/records#npis)
- [Conditions](https://www.flexpa.com/docs/records#conditions)
- [Validation](https://www.flexpa.com/docs/records#validation)

* * *

### [\#](https://www.flexpa.com/docs/records\#code-systems) Code systems

Healthcare data sources reference coding systems inconsistently in their FHIR implementations. Flexpa's code system normalization transform resolves these inconsistencies so you can match on a single canonical URI per code system. This transform:

1. **Resolves system URIs**: Maps nonstandard URIs, OIDs, and common variants (e.g., wrong case, `http` vs `https`, trailing `.html`) to canonical URIs
2. **Disambiguates by code format**: Distinguishes ICD-10-CM (diagnosis) from ICD-10-PCS (procedure) when both appear under a generic ICD-10 URI, and corrects CPT codes miscategorized under ICD-10 URIs
3. **Standardizes code values**: Reformats NDC codes to the standard 5-4-2 hyphenated format with zero-padding (e.g., `1234-5678-90` → `01234-5678-90`)

#### [\#](https://www.flexpa.com/docs/records\#benefits) Benefits

- **Simplified queries**: Match on canonical URIs without accounting for endpoint-specific variations
- **Accurate classification**: Diagnosis and procedure codes are assigned to the correct code system
- **Consistent formats**: Code values like NDC follow a single standard format

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-1) How it works

A set of global rules fixes common OID and URI variants for SNOMED, LOINC, RxNorm, CPT, ICD-10-CM, and HCPCS across all resource types in the bundle.
On ExplanationOfBenefit resources, additional rules resolve endpoint-specific and legacy URI variants, disambiguate codes like ICD-10-CM and ICD-10-PCS based on code format, and reformat NDC code values.

The [terminology](https://www.flexpa.com/docs/fhir/code-systems) reference lists all supported code systems and their canonical URIs.

### Before code system normalization

```json
{
  "resourceType": "ExplanationOfBenefit",
  "diagnosis": [{\
    "diagnosisCodeableConcept": {\
      "coding": [{\
        "system": "urn:oid:2.16.840.1.113883.6.90",\
        "code": "M54.5"\
      }]\
    }\
  }],
  "procedure": [{\
    "procedureCodeableConcept": {\
      "coding": [{\
        "system": "http://hl7.org/fhir/sid/icd-10",\
        "code": "0SRC0J9"\
      }]\
    }\
  }],
  "item": [{\
    "productOrService": {\
      "coding": [{\
        "system": "http://hl7.org/fhir/sid/ndc",\
        "code": "1234-5678-90"\
      }]\
    }\
  }]
}
```

CopyCopied!

### After code system normalization

```json
{
  "resourceType": "ExplanationOfBenefit",
  "diagnosis": [{\
    "diagnosisCodeableConcept": {\
      "coding": [{\
        "system": "http://hl7.org/fhir/sid/icd-10-cm",\
        "code": "M54.5"\
      }]\
    }\
  }],
  "procedure": [{\
    "procedureCodeableConcept": {\
      "coding": [{\
        "system": "http://www.cms.gov/Medicare/Coding/ICD10",\
        "code": "0SRC0J9"\
      }]\
    }\
  }],
  "item": [{\
    "productOrService": {\
      "coding": [{\
        "system": "http://hl7.org/fhir/sid/ndc",\
        "code": "01234-5678-90"\
      }]\
    }\
  }]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#tags) Tags

Flexpa adds standardized tags to all FHIR resources to provide consistent tracking and identification information. These tags help trace the origin of resources and provide additional context for your application.

Each resource is automatically tagged with the following metadata:

1. **Consent ID**: Unique identifier of the consent (OAuth authorization) that this data belongs to
2. **Patient Authorization ID**: Unique identifier of the patient authorization that sourced this data
3. **Endpoint ID**: Identifier of the health plan or provider endpoint that supplied the data
4. **Application ID**: Your application's identifier within the Flexpa system
5. **Patient Authorization Mode**: Whether the authorization was in `TEST` or `LIVE` mode
6. **Authorization Type**: The method used for authorization (e.g., `OAUTH`)

#### [\#](https://www.flexpa.com/docs/records\#benefits-1) Benefits

- **Traceability**: Easily identify the source of each resource in your system
- **Filtering**: Filter and organize resources by their origin or authorization type
- **Auditing**: Maintain a clear data lineage for compliance and record-keeping
- **Operational Insights**: Track which endpoints and authorization methods are providing your data

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-2) How It Works

The tags are added during data processing as part of the Flexpa transform pipeline and require no configuration. They're stored in the resource's `meta.tag` array as standard FHIR Coding objects, each with a Flexpa-specific system URI.

Each tag uses a specific system URL that identifies its purpose. You can use these system URLs to query for specific tags or filter resources programmatically.

#### System URLs

https://fhir.flexpa.com/identifiers/ConsentId

Identifies the consent (OAuth authorization) that this data belongs to

https://fhir.flexpa.com/identifiers/PatientAuthorizationId

Identifies the unique patient authorization that sourced this data

https://fhir.flexpa.com/identifiers/EndpointId

Indicates which health plan or provider endpoint supplied the data

https://fhir.flexpa.com/identifiers/ApplicationId

Identifies your application within the Flexpa system

https://fhir.flexpa.com/identifiers/PatientAuthorizationMode

Indicates if the authorization was in `TEST` or `LIVE` mode

https://fhir.flexpa.com/identifiers/AuthorizationType

Specifies the method used for authorization (e.g., `OAUTH`)

### Before Tagging Transform

```json
{
  "resourceType": "Patient",
  "id": "example-patient-id",
  "meta": {
    "lastUpdated": "2023-05-15T14:30:00Z"
  },
  "name": [\
    {\
      "family": "Smith",\
      "given": ["John"]\
    }\
  ]
}
```

CopyCopied!

### After Tagging Transform

```json
{
  "resourceType": "Patient",
  "id": "example-patient-id",
  "meta": {
    "lastUpdated": "2023-05-15T14:30:00Z",
    "tag": [\
      {\
        "system": "https://fhir.flexpa.com/identifiers/ConsentId",\
        "code": "f7e23a91-bc45-4d12-9e8f-1a2b3c4d5e6f"\
      },\
      {\
        "system": "https://fhir.flexpa.com/identifiers/PatientAuthorizationId",\
        "code": "8a350181-3115-49d7-a6aa-8e05b1cab08a"\
      },\
      {\
        "system": "https://fhir.flexpa.com/identifiers/EndpointId",\
        "code": "a5c22966-244d-4f36-b43a-4d4a619f89cc",\
        "display": "flexpa-sandbox"\
      },\
      {\
        "system": "https://fhir.flexpa.com/identifiers/ApplicationId",\
        "code": "062ca646-8d42-4753-9cd1-b39b234dd559"\
      },\
      {\
        "system": "https://fhir.flexpa.com/identifiers/PatientAuthorizationMode",\
        "code": "TEST"\
      },\
      {\
        "system": "https://fhir.flexpa.com/identifiers/AuthorizationType",\
        "code": "OAUTH"\
      }\
    ]
  },
  "name": [\
    {\
      "family": "Smith",\
      "given": ["John"]\
    }\
  ]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#identifiers) Identifiers

The Identifiers transform systematically replaces all resource IDs with deterministic UUIDv5 identifiers to ensure consistent and collision-free data handling across different health plans and authorizations. This transform:

1. **Preserves Original IDs**: Stores the original source ID in the resource's `identifier` array
2. **Creates Deterministic IDs**: Generates new IDs using UUIDv5 namespacing that remains consistent across syncs
3. **Updates References**: Updates all references within the bundle to use the new IDs
4. **Maintains Relationships**: Preserves the referential integrity between resources

#### [\#](https://www.flexpa.com/docs/records\#benefits-2) Benefits

- **Consistency**: Eliminates ID collisions between different payers using the same ID formats
- **Determinism**: Same resource from the same payer will always get the same ID
- **Traceability**: Original IDs are preserved in the `identifier` array for tracking
- **Interoperability**: Standardized ID format works across different systems and integrations

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-3) How It Works

The Identifiers transform uses UUIDv5 to deterministically generate UUIDs.
The input for the UUID is formed by concatenating the Resource Type, source ID, and endpoint ID.
A separate UUID is generated for the Patient resource belonging to the consenting patient and used as the namespace.

This approach ensures that:

- The same resource will always receive the same ID when synced again
- Resources from different patients remain distinct even if their original IDs were identical
- References between resources remain intact with the updated IDs

When working with FHIR data from Flexpa, always use the resource's ID for references rather than trying to reconstruct references from original identifiers.

### Before Identifiers Transform

```json
{
  "resourceType": "ExplanationOfBenefit",
  "id": "123456",
  "patient": {
    "reference": "Patient/98765"
  },
  "provider": {
    "reference": "Practitioner/PROV001"
  }
}
```

CopyCopied!

### After Identifiers Transform

```json
{
  "resourceType": "ExplanationOfBenefit",
  "id": "a1b2c3d4-e5f6-5a5a-b5c5-d5e5f5a5b5c5",
  "identifier": [\
    {\
      "system": "https://api.payer.com/fhir/ExplanationOfBenefit/SourceResourceId",\
      "value": "123456"\
    }\
  ],
  "patient": {
    "reference": "Patient/f9e8d7c6-b5a4-5b5b-c5d5-e5f5a5b5c5d5"
  },
  "provider": {
    "reference": "Practitioner/c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5"
  }
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#references) References

The References transform ensures that all FHIR references between resources are properly structured, resolvable, and consistent. This transform:

1. **Updates Resource IDs**: Ensures all references point to the new UUIDv5 IDs created by the [Identifiers](https://www.flexpa.com/docs/records#identifiers) transform
2. **Resolves NPI References**: Expands NPI identifiers into proper resource references as part of the [NPIs](https://www.flexpa.com/docs/records#npis) transform
3. **Handles Different Reference Types**: Works with all reference formats including relative, internal, and absolute references
4. **Preserves Source URLs**: Maintains original reference information by adding `source` and `fullUrl` metadata

#### [\#](https://www.flexpa.com/docs/records\#benefits-3) Benefits

- **Complete Navigation**: Users can follow references between resources without broken links
- **Consistent Referencing**: All references follow a standardized format
- **Traceability**: Original source URLs are preserved for auditing and debugging
- **Proper FHIR Structure**: References comply with FHIR specifications

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-4) How It Works

The References transform operates in multiple stages.

First, during the Identifiers transform, all references within resources are updated to use the new UUIDv5 IDs.

Second, during the NPI transform, identifiers with NPIs are expanded into full references to Provider resources.

Finally, during sourcing, `fullUrl` and `source` metadata are added to preserve origin information.

References between resources are a key part of the FHIR standard. Flexpa ensures that all references work properly so you can navigate between related resources.

### Before References Transform

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "123456",\
        "patient": {\
          "reference": "Patient/98765"\
        },\
        "provider": {\
          "identifier": {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "1234567890"\
          }\
        }\
      }\
    }\
  ]
}
```

CopyCopied!

### After References Transform

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "fullUrl": "https://api.payer.com/ExplanationOfBenefit/123456",\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "a1b2c3d4-e5f6-5a5a-b5c5-d5e5f5a5b5c5",\
        "meta": {\
          "source": "https://api.payer.com/ExplanationOfBenefit/123456"\
        },\
        "patient": {\
          "reference": "Patient/f9e8d7c6-b5a4-5b5b-c5d5-e5f5a5b5c5d5"\
        },\
        "provider": {\
          "reference": "Practitioner/c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",\
          "identifier": {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "1234567890"\
          }\
        }\
      }\
    },\
    {\
      "fullUrl": "https://api.payer.com/Practitioner/PROV001",\
      "resource": {\
        "resourceType": "Practitioner",\
        "id": "c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",\
        "meta": {\
          "source": "https://api.payer.com/Practitioner/PROV001"\
        },\
        "identifier": [\
          {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "1234567890"\
          }\
        ],\
        "name": [\
          {\
            "family": "Smith",\
            "given": ["John", "A"],\
            "prefix": ["Dr."]\
          }\
        ]\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#npis) NPIs

The National Provider Identifier (NPI) transform enhances FHIR bundles by enriching provider information using NPI references found in the data. When an NPI is detected in a FHIR resource, Flexpa automatically:

1. Identifies NPIs within the bundle
2. Looks up detailed provider information from those NPIs using the National Plan & Provider Enumeration System (NPPES)
3. Expands NPI references in the bundle to include full provider details
4. Backfills provider information such as names, addresses, specialties, and contact information

This transform works with both Practitioner and Organization resources, enhancing references in resources like Patient, Coverage, and ExplanationOfBenefit.

#### [\#](https://www.flexpa.com/docs/records\#benefits-4) Benefits

- **Richer Data**: Adds comprehensive provider details that may be missing in the original data
- **Consistent Provider Information**: Standardizes provider data across different payers and sources
- **Improved User Experience**: Enables applications to display detailed provider information without additional lookups

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-5) How It Works

The NPI transform runs automatically during data processing and works in three phases— **reference expansion**, **data backfilling**, and **resource resolution**.

- **Reference Expansion** – Converts bare NPI identifiers into full FHIR references and, when needed, creates the corresponding Practitioner or Organization resource.
- **Data Backfilling** – Enriches those provider resources with names, addresses, telecom details, and specialties sourced from NPPES.
- **Resource Resolution** – Revisits the bundle and rewires related resources so they point to the newly enriched provider entries, ensuring every resource has a proper, navigable reference path.

### Before NPI Transform

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "eob-12345",\
        "provider": {\
          "identifier": {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "1234567890"\
          }\
        }\
      }\
    }\
  ]
}
```

CopyCopied!

### After NPI Transform

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "a1b2c3d4-e5f6-5a5a-b5c5-d5e5f5a5b5c5",\
        "provider": {\
          "reference": "Practitioner/c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",\
          "identifier": {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "1234567890"\
          }\
        }\
      }\
    },\
    {\
      "resource": {\
        "resourceType": "Practitioner",\
        "id": "c9b8a7d6-e5f4-5c5c-d5e5-f5a5b5c5d5e5",\
        "identifier": [\
          {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "1234567890"\
          }\
        ],\
        "name": [\
          {\
            "family": "Smith",\
            "given": ["John", "A"],\
            "prefix": ["Dr."]\
          }\
        ],\
        "address": [\
          {\
            "line": ["123 Main St"],\
            "city": "Anytown",\
            "state": "CA",\
            "postalCode": "12345"\
          }\
        ],\
        "telecom": [\
          {\
            "system": "phone",\
            "value": "555-123-4567"\
          }\
        ],\
        "qualification": [\
          {\
            "code": {\
              "coding": [\
                {\
                  "system": "http://nucc.org/provider-taxonomy",\
                  "code": "207R00000X",\
                  "display": "Internal Medicine"\
                }\
              ]\
            }\
          }\
        ]\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#medications) Medications

**Preview**: This transform is in preview and is available to enterprise partners.

The Medications transform enhances FHIR bundles by creating MedicationRequest resources from pharmacy claims data found in ExplanationOfBenefit resources. This transform:

1. Identifies pharmacy claims in ExplanationOfBenefit resources
2. Extracts medication information from these claims
3. Creates structured MedicationRequest resources with proper references
4. Maintains bidirectional linkage between the source claims and derived medication requests

This process ensures that medication information is consistently available as MedicationRequest resources, even when the original payer API doesn't directly expose this data in that format.

#### [\#](https://www.flexpa.com/docs/records\#safety-notice) Safety Notice

MedicationRequest resources derived from pharmacy claims may not indicate medications that were actually dispensed or taken. Claims may have been denied or partially fulfilled. Check the associated ExplanationOfBenefit resources (in `supportingInformation`) for claim adjudication status.

#### [\#](https://www.flexpa.com/docs/records\#benefits-5) Benefits

- **Improved Medication Data Access**: Provides a standardized way to access medication information through the MedicationRequest resource type
- **Connected Resources**: Maintains proper references between medication requests and their source claims
- **Consistent Experience**: Creates a uniform experience across different payers, regardless of their underlying API implementation

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-6) How It Works

The Medications transform occurs automatically during data processing and includes:

- **Pharmacy Claim Identification**: Detects pharmacy claims in ExplanationOfBenefit resources by checking for pharmacy claim types
- **Medication Information Extraction**: Pulls medication codes, dates, and other details from the claims' `productOrService` fields
- **Resource Creation**: Generates MedicationRequest resources with `status: "unknown"` (indicating that the fulfillment status is unknown) and `intent: "order"` (indicating it was a medication order)
- **Reference Management**: Creates explicit bidirectional references:
  - Adds `supportingInformation` reference from MedicationRequest to source ExplanationOfBenefit
  - Adds `prescription` reference from ExplanationOfBenefit to the MedicationRequest
  - Includes `derivation-reference` extension to clearly mark resources created through this transform
- **Deduplication**: When multiple claims contain the same medication code, creates a single MedicationRequest with references to all source claims

### Before Medications Transform

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",\
        "type": {\
          "coding": [\
            {\
              "system": "http://terminology.hl7.org/CodeSystem/claim-type",\
              "code": "pharmacy"\
            }\
          ]\
        },\
        "item": [\
          {\
            "productOrService": {\
              "coding": [\
                {\
                  "system": "http://hl7.org/fhir/sid/ndc",\
                  "code": "12345-6789-01",\
                  "display": "Medication Name 20mg"\
                }\
              ]\
            }\
          }\
        ]\
      }\
    }\
  ]
}
```

CopyCopied!

### After Medications Transform

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "ExplanationOfBenefit",\
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",\
        "type": {\
          "coding": [\
            {\
              "system": "http://terminology.hl7.org/CodeSystem/claim-type",\
              "code": "pharmacy"\
            }\
          ]\
        },\
        "item": [\
          {\
            "productOrService": {\
              "coding": [\
                {\
                  "system": "http://hl7.org/fhir/sid/ndc",\
                  "code": "12345-6789-01",\
                  "display": "Medication Name 20mg"\
                }\
              ]\
            }\
          }\
        ],\
        "prescription": {\
          "reference": "MedicationRequest/b7c8d9e0-f1a2-3456-bcde-789012345678"\
        }\
      }\
    },\
    {\
      "resource": {\
        "resourceType": "MedicationRequest",\
        "id": "b7c8d9e0-f1a2-3456-bcde-789012345678",\
        "status": "unknown",\
        "intent": "order",\
        "medicationCodeableConcept": {\
          "coding": [\
            {\
              "system": "http://hl7.org/fhir/sid/ndc",\
              "code": "12345-6789-01",\
              "display": "Medication Name 20mg"\
            }\
          ]\
        },\
        "subject": {\
          "reference": "Patient/c1d2e3f4-5678-90ab-cdef-1234567890ab"\
        },\
        "authoredOn": "2023-01-15",\
        "supportingInformation": [\
          {\
            "reference": "ExplanationOfBenefit/a1b2c3d4-e5f6-7890-abcd-ef1234567890"\
          }\
        ],\
        "extension": [\
          {\
            "url": "http://hl7.org/fhir/StructureDefinition/derivation-reference",\
            "extension": [\
              {\
                "url": "reference",\
                "valueReference": {\
                  "reference": "ExplanationOfBenefit/a1b2c3d4-e5f6-7890-abcd-ef1234567890"\
                }\
              }\
            ]\
          }\
        ]\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#conditions) Conditions

The Conditions transform automatically adds **chronicity** and **clinical classification** data to FHIR Condition resources using two datasets from AHRQ's [Healthcare Cost and Utilization Project (HCUP)](https://hcup-us.ahrq.gov/). For every Condition with an ICD-10-CM code, Flexpa:

1. Classifies the condition as **Chronic**, **Not Chronic**, or **Unknown** using the [Chronic Condition Indicator Refined (CCIR)](https://hcup-us.ahrq.gov/toolssoftware/chronic_icd10/chronic_icd10.jsp) dataset
2. Maps the condition to one or more of **552 CCSR clinical categories** across 22 body systems using the [Clinical Classifications Software Refined (CCSR)](https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp) dataset

#### [\#](https://www.flexpa.com/docs/records\#benefits-6) Benefits

- **Filter by chronicity**: Identify chronic conditions without maintaining your own lookup tables
- **Group by body system**: Query conditions by clinical domain (e.g., circulatory, respiratory, endocrine)

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-7) How It Works

- **Chronicity extension**: Added to `Condition.extension` using `http://hl7.org/fhir/StructureDefinition/condition-related` with a `valueCoding` from system `https://api.flexpa.com/fhir/StructureDefinition/condition-chronicity`. Codes: `C` (Chronic), `NC` (Not Chronic), `U` (Unknown).
- **CCSR category codings**: Appended to `Condition.code.coding` with system `https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp`. Each coding includes the CCSR category code and description.
- **Body system categories**: Appended to `Condition.category` as CodeableConcepts with the same CCSR system URI. Body systems are derived from the 3-letter prefix of each CCSR category code (e.g., `END` for Endocrine).

### Before

```json
{
  "resourceType": "Condition",
  "code": {
    "coding": [\
      {\
        "system": "http://hl7.org/fhir/sid/icd-10-cm",\
        "code": "E11.9",\
        "display": "Type 2 diabetes mellitus without complications"\
      }\
    ]
  }
}
```

CopyCopied!

### After

```json
{
  "resourceType": "Condition",
  "code": {
    "coding": [\
      {\
        "system": "http://hl7.org/fhir/sid/icd-10-cm",\
        "code": "E11.9",\
        "display": "Type 2 diabetes mellitus without complications"\
      },\
      {\
        "system": "https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp",\
        "code": "END002",\
        "display": "Diabetes mellitus without complication"\
      },\
      {\
        "system": "https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp",\
        "code": "END005",\
        "display": "Diabetes mellitus, Type 2"\
      }\
    ]
  },
  "category": [\
    {\
      "coding": [\
        {\
          "system": "https://hcup-us.ahrq.gov/toolssoftware/ccsr/ccs_refined.jsp",\
          "code": "END",\
          "display": "Endocrine, Nutritional and Metabolic Diseases"\
        }\
      ],\
      "text": "Endocrine, Nutritional and Metabolic Diseases"\
    }\
  ],
  "extension": [\
    {\
      "url": "http://hl7.org/fhir/StructureDefinition/condition-related",\
      "valueCoding": {\
        "system": "https://api.flexpa.com/fhir/StructureDefinition/condition-chronicity",\
        "code": "C",\
        "display": "Chronic"\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

### [\#](https://www.flexpa.com/docs/records\#validation) Validation

The Validation transform uses the FHIR $validate operation to validate incoming resources and automatically fix common issues in a non-destructive way. Flexpa automatically:

1. Validates resources ingested by our pipeline
2. Applies non-destructive corrective fixes, such as marking required fields with a `data-absent-reason` when they are unknown

#### [\#](https://www.flexpa.com/docs/records\#benefits-7) Benefits

- **Semantic Clarity**: Clearly communicates when data is truly missing from a source system
- **Integrity**: Maintains data accuracy without accidental data loss
- **Interoperability**: Improves compatibility with downstream FHIR systems and consumers

#### [\#](https://www.flexpa.com/docs/records\#how-it-works-8) How it works

1. **$validate Operation**: Each incoming Bundle is sent to the FHIR `$validate` endpoint.
2. **Parse OperationOutcome**: The resulting `OperationOutcome` is inspected for structural `error` issues.
3. **Auto-correction**: Common issues are fixed non-destructively (e.g., convert scalars to arrays).
4. **Add `data-absent-reason`**: Missing required fields are annotated with the standard `data-absent-reason` extension and a value of `unknown`

### Before Validation

```json
{
  "resourceType": "ExplanationOfBenefit",
  "id": "example-id",
  "type": {
    "coding": [\
      {\
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",\
        "code": "pharmacy"\
      }\
    ]
  }
  // Missing required provider field
}
```

CopyCopied!

### After Validation

```json
{
  "resourceType": "ExplanationOfBenefit",
  "id": "example-id",
  "type": {
    "coding": [\
      {\
        "system": "http://terminology.hl7.org/CodeSystem/claim-type",\
        "code": "pharmacy"\
      }\
    ]
  },
  "provider": {
    "extension": [\
      {\
        "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",\
        "valueCode": "unknown"\
      }\
    ]
  }
}
```

CopyCopied!

* * *

## [\#](https://www.flexpa.com/docs/records\#provider-directory) Provider Directory

The Provider Directory is a searchable database of healthcare providers in the United States, powered by the National Plan and Provider Enumeration System (NPPES) data. You can use this directory to search for providers by NPI, name, specialty, location, and other criteria.

The Provider Directory is available through the FHIR API and allows you to:

- Search for providers using FHIR's standard search capabilities
- Retrieve detailed provider information including specialties, practice locations, and contact details
- Access provider data without requiring patient consent

Access to the Provider Directory requires an [Application Access Token](https://www.flexpa.com/docs/records#application-access-token), which you can obtain through the [Token Endpoint](https://www.flexpa.com/docs/consent#token).

[**NPPES Registry** The National Plan and Provider Enumeration System is the authoritative registry for healthcare provider information in the United States\\
\\
* * *\\
\\
Visit NPPES Website →](https://nppes.cms.hhs.gov/)

* * *

GEThttps://api.flexpa.com/fhir/Practitioner

### [\#](https://www.flexpa.com/docs/records\#practitioner) Practitioner

Individual healthcare providers can be accessed through the Practitioner resource. Each provider is identified by their National Provider Identifier (NPI) and includes details about their credentials, contact information, and practice locations.

#### Request headers

AuthorizationstringRequired

An `Authorization: Bearer` header value must be presented with an [Application Access Token](https://www.flexpa.com/docs/records#application-access-token)

#### Request parameters

\_projectstring

Static value `01956cb0-e18e-747a-8dba-265e83e1ade2` to search provider directory. Excluding this parameter will also return patient-specific records.

namestring

Search by provider name (first, last, or full name)

identifiertoken

Search by NPI (e.g., `identifier=http://hl7.org/fhir/sid/us-npi|1234567890`)

addressstring

Search by address components (city, state, postal code)

Flexpa supports all Practitioner SearchParameters defined in the [FHIR R4 specification](https://www.hl7.org/fhir/R4/practitioner.html#search), including active, email, family, given, phone, telecom, and more.

### Request

Search by NPISearch by name

GET

/fhir/Practitioner?identifier=\[npi\]&\_project=01956cb0-e18e-747a-8dba-265e83e1ade2

```bash
APP_TOKEN=your-application-access-token

curl "https://api.flexpa.com/fhir/Practitioner?identifier=http://hl7.org/fhir/sid/us-npi|1234567890&_project=01956cb0-e18e-747a-8dba-265e83e1ade2" \
  -H "Authorization: Bearer $APP_TOKEN"
```

CopyCopied!

### Response

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "Practitioner",\
        "id": "1234567890",\
        "identifier": [\
          {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "1234567890"\
          }\
        ],\
        "name": [\
          {\
            "family": "Smith",\
            "given": ["John", "A"],\
            "prefix": ["Dr."]\
          }\
        ],\
        "telecom": [\
          {\
            "system": "phone",\
            "value": "555-123-4567",\
            "use": "work"\
          }\
        ],\
        "address": [\
          {\
            "line": ["123 Main St"],\
            "city": "San Francisco",\
            "state": "CA",\
            "postalCode": "94105",\
            "country": "US"\
          }\
        ],\
        "gender": "male",\
        "qualification": [\
          {\
            "code": {\
              "coding": [\
                {\
                  "system": "http://terminology.hl7.org/CodeSystem/v2-0360",\
                  "code": "MD",\
                  "display": "Doctor of Medicine"\
                }\
              ]\
            }\
          }\
        ]\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

GEThttps://api.flexpa.com/fhir/Organization

### [\#](https://www.flexpa.com/docs/records\#organization) Organization

Healthcare organizations such as hospitals, clinics, and group practices can be accessed through the Organization resource. Each organization is identified by their National Provider Identifier (NPI) and includes details about their type, contact information, and locations.

#### Request headers

AuthorizationstringRequired

An `Authorization: Bearer` header value must be presented with an [Application Access Token](https://www.flexpa.com/docs/records#application-access-token)

#### Request parameters

\_projectstring

Static value `01956cb0-e18e-747a-8dba-265e83e1ade2` to search provider directory. Excluding this parameter will also return patient-specific records.

namestring

Search by organization name

identifiertoken

Search by NPI (e.g., `identifier=http://hl7.org/fhir/sid/us-npi|1234567890`)

addressstring

Search by address components (city, state, postal code)

Flexpa supports all Organization SearchParameters defined in the [FHIR R4 specification](https://www.hl7.org/fhir/R4/organization.html#search), including active, address-city, address-state, address-postalcode, email, phone, and more.

### Request

Search by NPISearch by name

GET

/fhir/Organization?identifier=\[npi\]&\_project=01956cb0-e18e-747a-8dba-265e83e1ade2

```bash
APP_TOKEN=your-application-access-token

curl "https://api.flexpa.com/fhir/Organization?identifier=http://hl7.org/fhir/sid/us-npi|2345678901&_project=01956cb0-e18e-747a-8dba-265e83e1ade2" \
  -H "Authorization: Bearer $APP_TOKEN"
```

CopyCopied!

### Response

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [\
    {\
      "resource": {\
        "resourceType": "Organization",\
        "id": "2345678901",\
        "identifier": [\
          {\
            "system": "http://hl7.org/fhir/sid/us-npi",\
            "value": "2345678901"\
          }\
        ],\
        "active": true,\
        "type": [\
          {\
            "coding": [\
              {\
                "system": "http://terminology.hl7.org/CodeSystem/organization-type",\
                "code": "prov",\
                "display": "Healthcare Provider"\
              }\
            ]\
          }\
        ],\
        "name": "Bay Area Medical Center",\
        "telecom": [\
          {\
            "system": "phone",\
            "value": "555-987-6543",\
            "use": "work"\
          },\
          {\
            "system": "email",\
            "value": "contact@bayareamedical.example.com",\
            "use": "work"\
          }\
        ],\
        "address": [\
          {\
            "line": ["456 Healthcare Blvd"],\
            "city": "San Francisco",\
            "state": "CA",\
            "postalCode": "94107",\
            "country": "US"\
          }\
        ]\
      }\
    }\
  ]
}
```

CopyCopied!

* * *

## [\#](https://www.flexpa.com/docs/records\#faq) FAQ

#### [\#](https://www.flexpa.com/docs/records\#which-fhir-version-does-the-api-support) Which FHIR version does the API support?

The API supports FHIR R4.

#### [\#](https://www.flexpa.com/docs/records\#does-the-api-support-cors) Does the API support CORS?

No, the API does not support CORS.

The [Quickstart repository](https://www.flexpa.com/docs/guides/quickstart) contains a simple example of a server making requests - replicating that behavior for both the Link operations but also subsequent FHIR requests is important for security.

* * *

POSThttps://api.flexpa.com/apply

### [\#](https://www.flexpa.com/docs/records\#apply) Apply

At Flexpa, our API is core to everything we do. If you're excited to work with us, applying by API is the best way to get our attention.

Find out more about how we work in the [Flexpa OS](https://os.flexpa.com/).

#### Parameters

namestringRequired

Your name

emailstringRequired

Your email address

whystringRequired

Why do you want to work at Flexpa?

locationstringRequired

Your location

resumestringRequired

A link to your resume

phonestring

A phone number where we can reach you

githubstring

A link to your GitHub profile

linkedinstring

A link to your LinkedIn profile

websitestring

A link to your personal website

twitterstring

A link to your Twitter profile

### Request

cURLJavaScript

POST

/apply

```bash
curl -X POST https://api.flexpa.com/apply \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Fizz Buzz",
    "email": "fizz@example.com",
    "why": "I want to work at Flexpa because...",
    "location": "Foobar, USA",
    "resume": "https://www.dropbox.com/s/123456789/resume.pdf",
    "phone": "555-555-5555",
    "github": "@fizzbuzz",
    "linkedin": "https://www.linkedin.com/in/fizz-buzz-123456789/",
    "website": "https://www.example.com/",
    "twitter": "@fizzbuzz"
  }'
```

CopyCopied!

* * *

## [\#](https://www.flexpa.com/docs/records\#next-steps) Next steps

[**Quickstart** Get started with a cloneable quickstart project\\
\\
* * *\\
\\
Try it out →](https://www.flexpa.com/docs/guides/quickstart)

[**Consent** Flexpa Consent is a client-side component to help your users link health plan data sources\\
\\
* * *\\
\\
Build with Flexpa Consent →](https://www.flexpa.com/docs/tools/link)

[Status](https://flexpastatus.com/) [Twitter](https://www.twitter.com/flexpa) [GitHub](https://www.github.com/flexpa)

© 2026 Flexpa. All rights reserved. FHIR® is the registered trademark of Health Level Seven International and the use does not constitute endorsement by HL7.