SMA API Reference

Detailed request and response examples for all SMA Endpoint Directory endpoints.

List States

Returns all 56 U.S. states and territories with their Medicaid FHIR implementation status. Supports filtering by implementation status, API vendor, patient access status, and FHIR version.

Method	Path	Description
GET	`/v1/sma/states`	List all states with summary info

Parameters

Parameter	Required	Type	Description
`implemented`	No	boolean	Filter by implementation status (`true` or `false`)
`vendor`	No	string	Filter by API vendor (e.g., `"Epic"`)
`status`	No	string	Filter by patient access status (e.g., `"In Production"`)
`fhir_version`	No	string	Filter by FHIR version (e.g., `"4.0.1"`)

Example

List implemented states using Epic

Request

Node.js

const response = await fetch(
  "https://api.fhirfly.io/v1/sma/states?implemented=true&vendor=Epic",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

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

Response

JSON

{
  "states": [
    {
      "id": "california",
      "state": "California",
      "abbreviation": "CA",
      "is_implemented": true,
      "api_vendor": "Epic",
      "patient_access_status": "In Production",
      "provider_directory_status": "In Production",
      "production_url_count": 5,
      "fhir_version": "4.0.1"
    },
    {
      "id": "colorado",
      "state": "Colorado",
      "abbreviation": "CO",
      "is_implemented": true,
      "api_vendor": "Epic",
      "patient_access_status": "In Production",
      "provider_directory_status": "In Production",
      "production_url_count": 3,
      "fhir_version": "4.0.1"
    }
  ],
  "total": 2,
  "meta": {
    "data_as_of": "2026-03-01T00:00:00Z",
    "source": "CMS SMA Endpoint Directory",
    "source_url": "https://github.com/CMSgov/SMA-Endpoint-Directory"
  }
}

Response Fields

Field	Type	Description
`states`	array	Array of state summaries
`total`	number	Number of states returned (after filters)
`meta`	object	Source attribution and data timestamp

State Summary Fields

Field	Type	Description
`id`	string	State identifier (e.g., `"california"`)
`state`	string	Display name (e.g., `"California"`)
`abbreviation`	string \| null	Two-letter abbreviation (e.g., `"CA"`)
`is_implemented`	boolean	Whether FHIR endpoints are implemented
`api_vendor`	string \| null	API vendor (e.g., `"Epic"`)
`patient_access_status`	string \| null	Patient access API status
`provider_directory_status`	string \| null	Provider directory API status
`production_url_count`	number	Number of production endpoint URLs
`fhir_version`	string \| null	FHIR version (e.g., `"4.0.1"`)

Get State

Returns full details for a specific state, including patient access endpoints (claims, PDex, formulary, CHIP), provider directory endpoints, contacts, and metadata.

The :state parameter accepts three formats:

Abbreviation: CA, NY, TX
Underscore ID: california, new_york
Display name: California, New York

Method	Path	Description
GET	`/v1/sma/states/:state`	Get full details for one state

Example

Get SMA details for California

Request

Node.js

const response = await fetch(
  "https://api.fhirfly.io/v1/sma/states/CA",
  {
    method: "GET",
    headers: {
    "x-api-key": "YOUR_API_KEY",
  }
  }
);

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

Response

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

Response Structure

`patient_access`

Patient access API details including FHIR endpoint URLs by category.

Field	Type	Description
`status`	string \| null	Implementation status (e.g., `"In Production"`)
`implementation_date`	string \| null	When the API was deployed (ISO date)
`fhir_version`	string \| null	FHIR version
`auth_protocol`	string \| null	Authentication protocol (e.g., `"OAuth 2.0"`)
`refresh_frequency`	string \| null	How often data is refreshed
`endpoints.claims`	string[]	Claims FHIR endpoint URLs
`endpoints.pdex`	string[]	Payer Data Exchange (PDex) endpoint URLs
`endpoints.formulary`	string[]	Drug formulary endpoint URLs
`endpoints.chip`	string[]	CHIP (Children's Health Insurance Program) endpoint URLs
`endpoints.capability_statement`	string[]	FHIR CapabilityStatement (metadata) URLs
`endpoints.sandbox`	string[]	Sandbox/testing endpoint URLs

`provider_directory`

Provider directory API details.

Field	Type	Description
`status`	string \| null	Implementation status
`implementation_date`	string \| null	When deployed (ISO date)
`fhir_version`	string \| null	FHIR version
`is_public`	boolean \| null	Whether the directory is publicly accessible
`refresh_frequency`	string \| null	How often data is refreshed
`endpoints.production`	string[]	Production endpoint URLs
`endpoints.capability_statement`	string[]	FHIR CapabilityStatement URLs
`endpoints.sandbox`	string[]	Sandbox endpoint URLs

`contacts`

Contact information for the state's Medicaid FHIR implementation.

Field	Type	Description
`member_phone`	string \| null	Member services phone number
`member_email`	string \| null	Member services email
`developer_contact`	string \| null	Developer/API contact
`pd_developer_contact`	string \| null	Provider directory developer contact
`registration_info`	string \| null	API registration URL or instructions
`pd_registration_info`	string \| null	Provider directory registration info

Error Response

If the state is not found, the API returns a 404:

{
  "error": "state_not_found",
  "message": "State not found",
  "provided": "XX"
}

Stats

Returns aggregate statistics across all 56 states and territories — implementation counts, vendor distribution, FHIR version breakdown, and provider directory metrics.

Method	Path	Description
GET	`/v1/sma/stats`	Get aggregate statistics

Example

Get SMA aggregate statistics

Request

Node.js

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

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

Response

JSON

{
  "summary": {
    "total_states": 56,
    "implemented": 42,
    "not_implemented": 14,
    "total_production_urls": 187
  },
  "by_vendor": {
    "Epic": 18,
    "Conduent": 6,
    "Gainwell": 5,
    "Deloitte": 4,
    "Other": 9
  },
  "by_patient_access_status": {
    "In Production": 38,
    "In Development": 4,
    "Not Started": 14
  },
  "by_fhir_version": {
    "4.0.1": 40,
    "3.0.2": 2
  },
  "by_auth_protocol": {
    "OAuth 2.0": 35,
    "SMART on FHIR": 5,
    "API Key": 2
  },
  "provider_directory": {
    "total_with_pd": 30,
    "by_status": {
      "In Production": 25,
      "In Development": 5
    }
  },
  "meta": {
    "data_as_of": "2026-03-01T00:00:00Z",
    "source": "CMS SMA Endpoint Directory",
    "source_url": "https://github.com/CMSgov/SMA-Endpoint-Directory"
  }
}

Response Fields

`summary`

Field	Type	Description
`total_states`	number	Total states and territories tracked (56)
`implemented`	number	States with active FHIR implementations
`not_implemented`	number	States without implementations
`total_production_urls`	number	Total production endpoint URLs across all states

Breakdowns

Each breakdown is an object mapping category values to counts, sorted by count descending.

Field	Description
`by_vendor`	Count of states by API vendor
`by_patient_access_status`	Count by patient access implementation status
`by_fhir_version`	Count by FHIR version
`by_auth_protocol`	Count by authentication protocol
`provider_directory.total_with_pd`	States with a provider directory implementation
`provider_directory.by_status`	Provider directory count by status

SDK Usage

Node.js

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

const client = new Fhirfly({ apiKey: "your-api-key" });

// List all implemented states
const list = await client.sma.listStates({ implemented: true });
console.log(`${list.total} states have FHIR endpoints`);

for (const state of list.states) {
  console.log(`${state.abbreviation}: ${state.api_vendor ?? "No vendor"}`);
}

// Get full details for California
const ca = await client.sma.getState("CA");
console.log(`Claims endpoints: ${ca.patient_access.endpoints.claims.length}`);
console.log(`Auth: ${ca.patient_access.auth_protocol}`);

// Get aggregate statistics
const stats = await client.sma.stats();
console.log(`${stats.summary.implemented} / ${stats.summary.total_states} states implemented`);

Required Scopes

connectivity.read — All SMA endpoints

SMA API Reference

List States

Parameters

Example

List implemented states using Epic

Response Fields

State Summary Fields

Get State

Example

Get SMA details for California

Response Structure

patient_access

provider_directory

contacts

Error Response

Stats

Example

Get SMA aggregate statistics

Response Fields

summary

Breakdowns

SDK Usage

Required Scopes

See Also

`patient_access`

`provider_directory`

`contacts`

`summary`