FHIRfly

https://fhirfly.io/docs
Admin
FHIRfly is a healthcare reference data platform offering APIs, SDKs, and tools for clinical data...
Tokens:213,346
Snippets:1,459
Trust Score:5.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quick Start: Search dm+d with Fhirfly

Source: https://fhirfly.io/docs/search-apis/dmd

Quick start example for searching dm+d concepts using the Fhirfly client. Requires an API key and the @fhirfly-io/terminology package.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for paracetamol products
const results = await client.dmd.search({
  q: "paracetamol"
});

console.log(`Found ${results.total} concepts`);
for (const item of results.items) {
  console.log(`[${item.concept_type}] ${item.code}: ${item.display}`);
}
```

--------------------------------

### Response shape examples (HTTP)

Source: https://fhirfly.io/docs/value-apis/loinc

Example GET requests using the shape query parameter to control response detail: compact, standard (default), and full.

```HTTP
# Minimal data
GET /v1/loinc/2339-0?shape=compact

# Standard data (default)
GET /v1/loinc/2339-0?shape=standard

# Full data with provenance
GET /v1/loinc/2339-0?shape=full
```

--------------------------------

### Install @fhirfly-io/shl and @fhirfly-io/terminology

Source: https://fhirfly.io/docs/shl/ehr-integration

Install the required SDK packages for EHR integration.

```bash
npm install @fhirfly-io/shl @fhirfly-io/terminology

```

--------------------------------

### initialize

Source: https://fhirfly.io/docs/mcp/api-reference

Start an MCP session and negotiate capabilities.

```APIDOC
## initialize

### Description
Start an MCP session and negotiate capabilities.

### Method
JSON-RPC 2.0 method

### Endpoint
POST /mcp

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Must be "2.0"
- **id** (number) - Required - Request ID
- **method** (string) - Required - Must be "initialize"
- **params.protocolVersion** (string) - Required - Protocol version (e.g., "2024-11-05")
- **params.capabilities** (object) - Optional - Client capabilities
- **params.clientInfo.name** (string) - Required - Client name
- **params.clientInfo.version** (string) - Required - Client version

### Request Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-mcp-client",
      "version": "1.0.0"
    }
  }
}

### Response
#### Success Response (200)
- **result.protocolVersion** (string) - Protocol version
- **result.capabilities.tools** (object) - Server capabilities
- **result.serverInfo.name** (string) - Server name

#### Response Example
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "fhirfly-mcp-server"
    }
  }
}
```

--------------------------------

### Install SHL SDK

Source: https://fhirfly.io/docs/shl/quickstart

Install the base SHL package or include the terminology package for FHIRfly API enrichment.

```bash
npm install @fhirfly-io/shl
```

```bash
npm install @fhirfly-io/shl @fhirfly-io/terminology
```

--------------------------------

### Configure Claude Desktop for Global Installation

Source: https://fhirfly.io/docs/mcp/claude-desktop

Use this configuration when the server is installed globally.

```json
{
  "mcpServers": {
    "fhirfly": {
      "command": "fhirfly-mcp-server",
      "env": {
        "FHIRFLY_API_KEY": "ffly_your_api_key_here"
      }
    }
  }
}
```

--------------------------------

### Install FHIRfly SDK via npm

Source: https://fhirfly.io/docs/getting-started/quickstart

Install the FHIRfly SDK from npm using the package name @fhirfly-io/terminology.

```bash
npm install @fhirfly-io/terminology

```

--------------------------------

### Install FHIRfly MCP Server Globally

Source: https://fhirfly.io/docs/mcp/claude-desktop

Install the package globally using npm if you prefer not to use npx.

```bash
npm install -g @fhirfly-io/mcp-server
```

--------------------------------

### Example Response from dm+d Search

Source: https://fhirfly.io/docs/search-apis/dmd

Example response from the dm+d search endpoint. Shows facets, items, pagination, and legal metadata.

```json
{
  "facets": {
    "concept_type": {
      "VMP": 45,
      "AMP": 120,
      "VMPP": 38,
      "AMPP": 95,
      "VTM": 2
    }
  },
  "has_more": true,
  "items": [
    {
      "code": "90332006",
      "code_system": "dm+d",
      "concept_type": "VTM",
      "name": "Paracetamol",
      "display": "Paracetamol"
    },
    {
      "code": "39732311000001104",
      "code_system": "dm+d",
      "concept_type": "VMP",
      "name": "Paracetamol 500mg tablets",
      "display": "Paracetamol 500mg tablets"
    }
  ],
  "limit": 2,
  "meta": {
    "legal": {
      "attribution_required": true,
      "citation": "dm+d, NHS England / NHSBSA. Crown copyright. Open Government Licence v3.0.",
      "license": "OGL-UK-3.0",
      "source_name": "NHS dm+d"
    }
  },
  "page": 1,
  "total": 300,
  "total_capped": false
}
```

--------------------------------

### Install @fhirfly-io/shl package

Source: https://fhirfly.io/docs/shl/troubleshooting

Install the SHL SDK package using npm. Requires Node.js 18+ for built-in crypto and fetch support.

```bash
npm install @fhirfly-io/shl
```

--------------------------------

### Initialize AzureStorage

Source: https://fhirfly.io/docs/shl/storage-adapters

Install the required Azure storage dependency and configure the AzureStorage adapter using a connection string.

```bash
npm install @azure/storage-blob
```

```typescript
const storage = new SHL.AzureStorage({
  container: "shl-data",
  connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING,
  baseUrl: "https://shl.example.com",
  prefix: "shl-data/", // optional
});
```

--------------------------------

### GET /v1/snomed/:concept_id

Source: https://fhirfly.io/docs/value-apis/snomed

Example of a single concept lookup using the SNOMED CT API.

```APIDOC
## GET /v1/snomed/:concept_id

### Description
Retrieve a single SNOMED CT concept by its concept ID from the IPS Free Set.

### Method
GET

### Endpoint
/v1/snomed/:concept_id

### Parameters
#### Path Parameters
- **concept_id** (string) - Required - The SNOMED CT concept identifier (e.g., 73211009).

### Request Example
No request body required.

### Response
#### Success Response (200)
- **data** (object) - Contains the concept details.
  - **concept_id** (string) - The SNOMED CT concept identifier.
  - **active** (boolean) - Whether the concept is active.
  - **fsn** (string) - The fully specified name.
  - **preferred_term** (string) - The preferred term.
  - **synonyms** (array of strings) - List of synonyms.
  - **ips_category** (string) - The IPS category.
  - **semantic_tag** (string) - The semantic tag.
- **meta** (object) - Metadata about the source and legal information.
  - **source** (object) - Source details.
    - **name** (string) - Source name.
    - **url** (string) - Source URL.
    - **version** (string) - Source version.
  - **legal** (object) - Legal information.
    - **license** (string) - License type.
    - **attribution_required** (boolean) - Whether attribution is required.
    - **source_name** (string) - Source name.
    - **citation** (string) - Citation text.

#### Response Example
```json
{
  "data": {
    "concept_id": "73211009",
    "active": true,
    "fsn": "Diabetes mellitus (disorder)",
    "preferred_term": "Diabetes mellitus",
    "synonyms": [
      "DM - Diabetes mellitus",
      "Diabetes mellitus, NOS"
    ],
    "ips_category": "condition",
    "semantic_tag": "disorder"
  },
  "meta": {
    "source": {
      "name": "SNOMED CT IPS Free Set",
      "url": "https://www.snomed.org/our-standards/ips-terminology",
      "version": "IPS 1.1.0"
    },
    "legal": {
      "license": "CC BY 4.0",
      "attribution_required": true,
      "source_name": "SNOMED CT IPS Free Set",
      "citation": "SNOMED CT IPS Free Set. SNOMED International. Licensed under CC BY 4.0."
    }
  }
}
```
```

--------------------------------

### Initialize S3Storage

Source: https://fhirfly.io/docs/shl/storage-adapters

Install the required AWS SDK dependency and configure the S3Storage adapter for production workloads.

```bash
npm install @aws-sdk/client-s3
```

```typescript
const storage = new SHL.S3Storage({
  bucket: "my-shl-bucket",
  region: "us-east-1",
  baseUrl: "https://shl.example.com",
  prefix: "shl-data/", // optional
});
```

--------------------------------

### Quick Start: Search HCPCS Codes with Node.js

Source: https://fhirfly.io/docs/search-apis/hcpcs

Quick start example for searching HCPCS codes with the FHIRfly Node.js client. Requires an API key and the @fhirfly-io/terminology package. Searches for 'ambulance' and logs the total count and each code/display pair.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for ambulance-related HCPCS codes
const results = await client.hcpcs.search({
  q: "ambulance"
});

console.log(`Found ${results.total} codes`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### Run a full round-trip demo with fhirfly-shl demo

Source: https://fhirfly.io/docs/shl/cli-reference

Runs a full round-trip demo: builds an IPS bundle, creates an SHL, and optionally starts a server. Options include --port and --no-serve.

```bash
fhirfly-shl demo [options]
```

--------------------------------

### fhirfly-shl demo

Source: https://fhirfly.io/docs/shl/cli-reference

Runs a full round-trip demo: builds an IPS bundle, creates an SHL, and optionally starts a server. Supports port and no-serve options.

```APIDOC
## fhirfly-shl demo

### Description
Runs a full round-trip demo: build IPS bundle, create SHL, optionally start server.

### Usage
fhirfly-shl demo [options]

### Options
- `--port <number>` - Server port (default: `3456`)
- `--no-serve` - Skip starting the local server

```

--------------------------------

### Retrieve OPCS-4 code data with different shape parameters

Source: https://fhirfly.io/docs/value-apis/opcs4

Examples of GET requests for OPCS-4 codes using compact, standard, and full response shapes.

```http
# Minimal data
GET /v1/opcs4/W37.1?shape=compact

# Standard data (default)
GET /v1/opcs4/W37.1?shape=standard

# Full data with provenance
GET /v1/opcs4/W37.1?shape=full
```

--------------------------------

### Look up MUE limits for an office visit

Source: https://fhirfly.io/docs/claims/mue

Example request to retrieve MUE limits for HCPCS code 99213 using the GET /v1/mue/:hcpcs endpoint.

```javascript
const response = await fetch(
  "https://api.fhirfly.io/v1/mue/99213",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);
```

--------------------------------

### Initialize GCSStorage

Source: https://fhirfly.io/docs/shl/storage-adapters

Install the required Google Cloud storage dependency and configure the GCSStorage adapter for GCP deployments.

```bash
npm install @google-cloud/storage
```

```typescript
const storage = new SHL.GCSStorage({
  bucket: "my-shl-bucket",
  baseUrl: "https://shl.example.com",
  prefix: "shl-data/", // optional
});
```

--------------------------------

### CVX API shape query parameter examples

Source: https://fhirfly.io/docs/value-apis/cvx

Shows three GET requests to /v1/cvx/207 with shape=compact, shape=standard (default), and shape=full to control response detail levels.

```http
# Minimal data
GET /v1/cvx/207?shape=compact

# Standard data (default)
GET /v1/cvx/207?shape=standard

# Full data with provenance
GET /v1/cvx/207?shape=full
```

--------------------------------

### Retrieve dm+d data with different shape parameters

Source: https://fhirfly.io/docs/value-apis/dmd

Examples of GET requests to the dm+d API using the shape query parameter to control the level of detail in the response.

```http
# Minimal data
GET /v1/dmd/39732311000001104?shape=compact

# Standard data (default)
GET /v1/dmd/39732311000001104?shape=standard

# Full data with provenance
GET /v1/dmd/39732311000001104?shape=full
```

--------------------------------

### Show CLI help with npx @fhirfly-io/shl --help

Source: https://fhirfly.io/docs/shl/cli-reference

Displays the CLI help and available commands.

```bash
npx @fhirfly-io/shl --help
```

--------------------------------

### Requesting HCC data with different shape parameters

Source: https://fhirfly.io/docs/value-apis/hcc

Examples of GET requests for HCC data using the compact, standard, and full shape query parameters to control response detail.

```http
# Minimal data
GET /v1/hcc/E11.9?shape=compact

# Standard data (default)
GET /v1/hcc/E11.9?shape=standard

# Full data with provenance
GET /v1/hcc/E11.9?shape=full
```

--------------------------------

### API Key format examples

Source: https://fhirfly.io/docs/getting-started/authentication

Distinguish between production and test/sandbox environments using the API key prefix.

```text
ffly_sk_live_abc123...  # Production key
ffly_sk_test_abc123...  # Test/sandbox key
```

--------------------------------

### Reverse Lookup with model_version Filter (GET)

Source: https://fhirfly.io/docs/value-apis/hcc

Use the model_version query parameter to filter reverse lookup results to a specific CMS-HCC model. This example requests HCC 19 with model version V24.

```HTTP
GET /v1/hcc/reverse/19?model_version=V24
```

--------------------------------

### Run the live exercise integration test

Source: https://fhirfly.io/docs/shl/overview

Run the comprehensive integration test that exercises all SDK paths against the live API. Requires an API key and optionally the --verbose flag. Useful for smoke-testing deployment or as a usage reference.

```bash
npx tsx examples/live-exercise/index.ts --api-key <key> --verbose
```

--------------------------------

### Forward Lookup with model_version Filter (GET)

Source: https://fhirfly.io/docs/value-apis/hcc

Use the model_version query parameter to filter forward lookup results to a specific CMS-HCC model. This example requests ICD-10 code E11.9 with model version V28.

```HTTP
GET /v1/hcc/E11.9?model_version=V28
```

--------------------------------

### Low-Level PSHD Mode and Profile Options

Source: https://fhirfly.io/docs/shl/pshd

Use mode: "direct" and profile: "pshd" independently for fine-grained control. The first example shows direct mode without PSHD bundle constraints; the second shows building a PSHD bundle profile without direct mode.

```javascript
// Direct mode without PSHD bundle constraints
const result = await SHL.create({
  bundle: anyFhirBundle,    // does not need to be a PSHD bundle
  storage,
  mode: "direct",           // flag U, single-request retrieval
  expiresAt: new Date(Date.now() + 60 * 60_000),  // optional here
});
```

```javascript
// PSHD bundle profile without direct mode
const fhirBundle = await bundle.build({ profile: "pshd" });
// produces a collection bundle with CMS DocumentReference constraints
```

--------------------------------

### ICD-10 API shape parameter examples

Source: https://fhirfly.io/docs/value-apis/icd10

Shows three GET requests to the ICD-10 API endpoint `/v1/icd10/E11.9` with different `shape` values: `compact`, `standard` (default), and `full`. Use these to control the level of detail in responses.

```http
# Minimal data
GET /v1/icd10/E11.9?shape=compact

# Standard data (default)
GET /v1/icd10/E11.9?shape=standard

# Full data with provenance
GET /v1/icd10/E11.9?shape=full
```

--------------------------------

### Quick Start with Node.js

Source: https://fhirfly.io/docs/search-apis/mvx

Initialize the FHIRfly client and perform a basic search for vaccine manufacturers by name.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for Pfizer
const results = await client.mvx.search({
  q: "pfizer"
});

console.log(`Found ${results.total} manufacturers`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```

--------------------------------

### Get SMA details for California - JSON response

Source: https://fhirfly.io/docs/sma/api-reference

Example JSON response for the California state request. Shows the structure including patient access endpoints, provider directory, contacts, and metadata. The response is 69 lines long.

```JSON
{
  "id": "california",
  "state": "California",
  "abbreviation": "CA",
  "api_vendor": "Epic",
  "survey_date": "2026-01-15",
  "is_implemented": true,
  "patient_access": {
    "status": "In Production",
    "implementation_date": "2024-07-01",
    "fhir_version": "4.0.1",
    "auth_protocol": "OAuth 2.0",
    "refresh_frequency": "Daily",
    "endpoints": {
      "claims": [
        "https://fhir.example.ca.gov/R4/Claims"
      ],
      "pdex": [
        "https://fhir.example.ca.gov/R4/PDex"
      ],
      "formulary": [
        "https://fhir.example.ca.gov/R4/Formulary"
      ],
      "chip": [],
      "capability_statement": [
        "https://fhir.example.ca.gov/R4/metadata"
      ],
      "sandbox": [
        "https://sandbox.fhir.example.ca.gov/R4"
      ]
    }
  },
  "provider_directory": {
    "status": "In Production",
    "implementation_date": "2024-07-01",
    "fhir_version": "4.0.1",
    "is_public": true,
    "refresh_frequency": "Weekly",
    "endpoints": {
      "production": [
        "https://pd.fhir.example.ca.gov/R4"
      ],
      "capability_statement": [
        "https://pd.fhir.example.ca.gov/R4/metadata"
      ],
      "sandbox": []
    }
  },
  "contacts": {
    "member_phone": "1-800-555-0100",
    "member_email": "members@example.ca.gov",
    "developer_contact": "developer@example.ca.gov",
    "pd_developer_contact": null,
    "registration_info": "https://developer.example.ca.gov/register",
    "pd_registration_info": null
  },
  "all_production_urls": [
    "https://fhir.example.ca.gov/R4/Claims",
    "https://fhir.example.ca.gov/R4/PDex",
    "https://fhir.example.ca.gov/R4/Formulary",
    "https://pd.fhir.example.ca.gov/R4"
  ],
  "meta": {
    "data_as_of": "2026-03-01T00:00:00Z",
    "source": "CMS SMA Endpoint Directory",
    "source_url": "https://github.com/CMSgov/SMA-Endpoint-Directory",
    "ingested_at": "2026-03-01T12:00:00Z"
  }
}
```

--------------------------------

### Serve SHLs locally with fhirfly-shl serve

Source: https://fhirfly.io/docs/shl/cli-reference

Starts a local HTTP server for serving SHLs. Options include --port and --dir.

```bash
fhirfly-shl serve [options]
```

--------------------------------

### HCPCS response shape examples

Source: https://fhirfly.io/docs/value-apis/hcpcs

Shows three GET requests to /v1/hcpcs/A0425 with different shape values: compact for minimal data, standard for default detail, and full for data with provenance. Use the shape query parameter to control response detail.

```HTTP
# Minimal data
GET /v1/hcpcs/A0425?shape=compact

# Standard data (default)
GET /v1/hcpcs/A0425?shape=standard

# Full data with provenance
GET /v1/hcpcs/A0425?shape=full
```

--------------------------------

### NDC API shape query parameter examples

Source: https://fhirfly.io/docs/value-apis/ndc

Shows three GET requests to the NDC API using the `shape` query parameter to request compact, standard (default), and full response shapes. The `compact` shape is for minimal data, `standard` is the default core structured data, and `full` includes provenance for AI agents.

```http
GET /v1/ndc/60505008100?shape=compact
```

```http
GET /v1/ndc/60505008100?shape=standard
```

```http
GET /v1/ndc/60505008100?shape=full
```

--------------------------------

### Initialize Session Request

Source: https://fhirfly.io/docs/mcp/api-reference

Start an MCP session and negotiate capabilities with the server.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-mcp-client",
      "version": "1.0.0"
    }
  }
}
```

--------------------------------

### Single Drug DDI Reference Lookup (GET /v1/ddi/reference/:identifier)

Source: https://fhirfly.io/docs/value-apis/ddi

Use this Node.js fetch call to retrieve FDA interaction text and drug metadata for a single drug by RxCUI, NDC, or FDA set_id. The response includes drug classes, ingredients, and DailyMed links. The example uses ramipril (RxCUI 261962) and requires an API key.

```javascript
const response = await fetch(
  "https://api.fhirfly.io/v1/ddi/reference/261962",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

const data = await response.json();
console.log(data);
```

```json
{
  "data": {
    "input": "261962",
    "status": "ok",
    "drug": {
      "rxcui": "261962",
      "name": "ramipril 10 MG Oral Capsule",
      "generic_name": [
        "RAMIPRIL"
      ],
      "brand_names": [],
      "substance_name": [
        "Ramipril"
      ],
      "pharm_class_epc": [
        "Angiotensin Converting Enzyme Inhibitor [EPC]"
      ],
      "drug_classes": [
        {
          "class_id": "N0000000181",
          "class_name": "Angiotensin-converting Enzyme Inhibitors [MoA]",
          "class_type": "MoA",
          "source": "med-rt"
        },
        {
          "class_id": "N0000178477",
          "class_name": "Decreased Blood Pressure [PE]",
          "class_type": "PE",
          "source": "med-rt"
        }
      ],
      "ingredients": []
    },
    "label": {
      "spl_id": "0bfa08c7-2c74-4436-aa35-8cd37a21bd75",
      "set_id": "e8d9a115-71a7-4580-abbd-865e98b5d3f6",
      "dailymed_url": "https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid=e8d9a115-71a7-4580-abbd-865e98b5d3f6",
      "sections": {
        "drug_interactions": [
          "7 DRUG INTERACTIONS..."
        ]
      }
    }
  },
  "meta": {
    "legal": {
      "license": "public_domain",
      "attribution_required": false,
      "disclaimer": "Drug interaction data is sourced from FDA-approved labeling and NLM RxNorm. This is reference information only...",
      "sources": [
        {
          "name": "FDA openFDA Drug Labels",
          "url": "https://open.fda.gov/apis/drug/label/"
        },
        {
          "name": "NLM RxNorm",
          "url": "https://www.nlm.nih.gov/research/umls/rxnorm/"
        }
      ]
    }
  }
}
```

--------------------------------

### Import SDK and initialize FHIRfly client

Source: https://fhirfly.io/docs/shl/ehr-integration

Import the SDK classes and initialize the optional FHIRfly enrichment client. Without an API key, you must provide display names manually.

```javascript
import { IPS, SHL } from "@fhirfly-io/shl";
import Fhirfly from "@fhirfly-io/terminology";

// FHIRfly API enriches your codes with display names, SNOMED mappings, etc.
// Optional but recommended — without it, you provide display names manually.
const fhirfly = new Fhirfly({ apiKey: process.env.FHIRFLY_API_KEY });

```

--------------------------------

### Node.js Quick Start

Source: https://fhirfly.io/docs/search-apis/icd10

Initializes the FHIRfly client and performs a basic search for diabetes diagnosis codes.

```javascript
import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "YOUR_API_KEY" });

// Search for diabetes diagnosis codes
const results = await client.icd10.search({
  q: "diabetes",
  code_system: "CM"
});

console.log(`Found ${results.total} codes`);
for (const item of results.items) {
  console.log(`${item.code}: ${item.display}`);
}
```
Tokens:
Raw