FHIR Explorer API Documentation

Overview

The FHIR Explorer Microservice provides AI-optimized JSON schemas for FHIR resources with comprehensive identifier validation, clinical appropriateness enforcement, and EMR-ready format specifications.

Important: This API analyzes FHIR resource structures and provides field metadata - it is NOT a workflow management or business requirements system. If you're seeing workflow data in your responses, you may be calling a different API endpoint.

Base URL: https://your-deployment-url.com or http://localhost:5000 for local development

Authentication

No authentication required - this is a public API for FHIR structure analysis.

Rate Limiting

- Limit: 60 requests per minute per IP address - Headers: Response includes rate limit information in headers: - X-RateLimit-Limit: Maximum requests per minute - X-RateLimit-Remaining: Remaining requests in current window - X-RateLimit-Reset: Unix timestamp when limit resets

Endpoints

1. Analyze FHIR Resource

Endpoint: GET /api/v1/analyze/{resource}

Converts FHIR StructureDefinitions into AI-optimized JSON schemas with field metadata, validation rules, and clinical identifier validation.

Parameters

Parameter Type Required Default Options Description
resource string Yes - Any FHIR R4 resource FHIR resource type (e.g., Patient, Practitioner, Organization)
specification string No us-core us-core, generic-r4 Specification type for analysis
version string No latest Any valid version US Core IG version (only applies to us-core specification)
filter string No all all, important Field filtering: all fields or MoSCoW Must/Should only
validations boolean No true true, false Include validation rules in response
nested boolean No true true, false Include nested structure or flat response

Response Schema

{   "resourceType": "string",   "meta": {     "totalElements": "number",     "requiredElements": "number",     "optionalElements": "number",     "identifierElements": "number",     "validationRules": "number"   },   "elements": [     {       "path": "string",       "fhirPath": "string",        "type": "string",       "cardinality": "string",       "required": "boolean",       "moscow": "must|should|could|wont",       "label": "string",       "description": "string",       "binding": {         "valueSet": "string",         "strength": "required|extensible|preferred|example",         "options": [           {             "code": "string",             "display": "string",             "system": "string"           }         ]       },       "referenceTarget": ["string"],       "validations": [         {           "type": "string",           "value": "string|number|boolean",           "message": "string"         }       ],       "uiHint": "textbox|textarea|singleSelect|multiSelect|datePicker|checkbox|radio|numberInput",       "children": ["FieldElement"],       "extension": "boolean",       "extensions": ["ExtensionInfo"]     }   ],   "specVersion": "string",   "generatedAt": "string" }

2. List Supported Resources

Endpoint: GET /api/v1/resources

Returns a complete list of all supported FHIR resource types. This API supports all 150+ FHIR R4 resources with comprehensive identifier validation.

Response

{   "resources": [     "Account", "ActivityDefinition", "AdverseEvent", "AllergyIntolerance",     "Appointment", "AppointmentResponse", "AuditEvent", "Basic", "Binary",     "// ... all 150+ FHIR R4 resources"   ],   "total": 150,   "specifications": ["us-core", "generic-r4"],   "description": "All FHIR R4 resources supported with clinical identifier validation and EMR-ready schemas" }

3. Health Check

Endpoint: GET /health

System health and status information.

Response

{   "status": "healthy|starting|degraded",   "frontend": "Flask",   "backend": {     "service": "fhir-explorer",     "status": "healthy",      "version": "1.2.0"   },   "deployment": "unified",   "proxy": "operational" }

API Testing with Insomnia & Postman

Insomnia Setup

1. Create New Request

• Open Insomnia and create a new HTTP Request • Set method to GET • Set URL to: https://your-deployment-url.com/api/v1/analyze/Patient • No headers required - all parameters are in the URL

2. Configure Query Parameters

• Click on "Query" tab • Add parameters (start with just one parameter): - specification: generic-r4 (Options: generic-r4 or us-core) - filter: important (Recommended: important for essential fields, all for complete schema but may be slower) - validations: true (Options: true or false) - nested: true (Options: true or false)

Important: Start with just the filter=important parameter first, then add others one by one.

3. Environment Variables (Optional)

• Create environment: FHIR_Explorer • Add variable: base_url = https://your-deployment-url.com • Use: {{base_url}}/api/v1/analyze/Patient

4. Parameter Options Reference

Specification Options: - generic-r4: Standard FHIR R4 validation and structure - us-core: US Core Implementation Guide constraints and profiles

Filter Options: - important: Returns only MoSCoW "Must" and "Should" priority fields (recommended for forms) - all: Returns all available fields including optional ones (larger response, may be slower)

Validation Options: - true: Includes regex patterns, format rules, and clinical validation - false: Excludes validation rules for faster response

Nested Options: - true: Returns hierarchical structure with parent-child relationships - false: Returns flat structure with all fields at root level

4. Sample Requests

Analyze Practitioner: 

GET https://your-deployment-url.com/api/v1/analyze/Practitioner?specification=generic-r4&filter=all&validations=true&nested=true

Analyze Patient (Important Fields Only): 

GET https://your-deployment-url.com/api/v1/analyze/Patient?specification=us-core&filter=important&validations=true

List All Supported Resources: 

GET https://your-deployment-url.com/api/v1/resources

Health Check: 

GET https://your-deployment-url.com/health

5. Working Example URLs

Try these exact URLs that are confirmed working:

WORKING - Basic Patient Analysis (no parameters): 

https://your-deployment-url.com/api/v1/analyze/Patient

WORKING - Patient with important fields only: 

https://your-deployment-url.com/api/v1/analyze/Patient?filter=important

WORKING - Patient with specification: 

https://your-deployment-url.com/api/v1/analyze/Patient?specification=generic-r4

List all resources: 

https://your-deployment-url.com/api/v1/resources

6. Expected Response Format

When successful, you'll get dropdown options like this:

{   "resourceType": "Patient",   "elements": [     {       "path": "Patient.identifier.type",       "type": "CodeableConcept",       "uiHint": "singleSelect",       "binding": {         "options": [           {             "code": "MR",             "display": "Medical Record Number"           },           {             "code": "MC",              "display": "Medicare Number"           }         ]       }     }   ] }
Postman Setup
1. Create New Collection
 • Create collection: "FHIR Explorer API" • Add new request: "Analyze FHIR Resource" • Set method to GET • No headers needed - simple GET requests only
2. Request Configuration
 URL:
https://your-deployment-url.com/api/v1/analyze/Patient 
 Headers: None required
Query Parameters: - specification: generic-r4 (or us-core) - filter: all (or important for Must/Should fields only) - validations: true (or false to exclude validation rules) - nested: true (or false for flat structure)
3. Environment Setup
 • Click "Environments" → "Create Environment" • Name: "FHIR Explorer API" • Variable: api_url = https://your-deployment-url.com • Use: {{api_url}}/api/v1/analyze/Patient
4. Tests & Automation
 Add to "Tests" tab:
javascript // Test response status pm.test("Status code is 200", function () { pm.response.to.have.status(200); });

// Test response structure pm.test("Response has resourceType", function () { var jsonData = pm.response.json(); pm.expect(jsonData).to.have.property('resourceType'); pm.expect(jsonData).to.have.property('elements'); });

// Test identifier validation pm.test("Identifier validation present", function () { var jsonData = pm.response.json(); var identifierElement = jsonData.elements.find(e => e.path.includes('identifier')); if (identifierElement) { pm.expect(identifierElement).to.have.property('binding'); } });

// Save resource type for follow-up requests pm.test("Save resource type", function () { var jsonData = pm.response.json(); pm.environment.set("resource_type", jsonData.resourceType); }); 

 
Form Options & Dropdowns
The FHIR Explorer API provides rich dropdown options for form building. Here's how to use them:
Understanding Binding Options
When you receive a response, look for elements with binding properties:
json { "path": "Patient.identifier.type", "type": "CodeableConcept", "uiHint": "singleSelect", "binding": { "valueSet": "http://hl7.org/fhir/ValueSet/identifier-type", "strength": "extensible", "options": [ { "code": "MR", "display": "Medical Record Number (6-12 character alphanumeric medical record identifier)", "system": "http://terminology.hl7.org/CodeSystem/v2-0203" }, { "code": "MC", "display": "Patient's Medicare Number (9 digits followed by 2 letters (Medicare format))", "system": "http://terminology.hl7.org/CodeSystem/v2-0203" } ] } } 
 
Building Form Dropdowns
For Single Select (CodeableConcept):
html 
 For Multi-Select (Multiple CodeableConcept):
html 
 
Clinical Identifier Validation
The API enforces clinical appropriateness:
Patient Identifiers (Allowed): - MR (Medical Record Number) - MC (Medicare Number)  - MA (Medicaid Number) - SSN (Social Security Number)
Practitioner Identifiers (Allowed): - NPI (National Provider Identifier) - SL (State License Number) - TAX (Tax ID Number)
Cross-Resource Prevention: - Patients cannot have NPI or DEA numbers - Practitioners cannot have Medicare or Medical Record numbers
Form Validation Rules
Use the validations array for client-side validation:
json { "validations": [ { "type": "pattern", "value": "^[0-9]{10}$", "message": "NPI must be exactly 10 digits" }, { "type": "required", "value": true, "message": "This field is required" } ] } 
 
Sample Form Implementation
javascript // Build dropdown from API response function buildIdentifierTypeDropdown(element) { const select = document.createElement('select'); select.name = element.path; if (element.binding && element.binding.options) { element.binding.options.forEach(option => { const optionEl = document.createElement('option'); optionEl.value = option.code; optionEl.textContent = option.display; select.appendChild(optionEl); }); } return select; }

// Validate based on rules function validateField(value, validations) { for (const rule of validations) { if (rule.type === 'pattern' && !new RegExp(rule.value).test(value)) { return { valid: false, message: rule.message }; } if (rule.type === 'required' && rule.value && !value) { return { valid: false, message: rule.message }; } } return { valid: true }; } 

 
Quick Import Collection
Copy this Postman collection JSON to quickly import all endpoints:
Postman Setup & Examples
Quick Import (Recommended)
 1. Copy JSON below and save as FHIR-Explorer.postman_collection.json 2. Import in Postman: File → Import → Upload Files 3. Set Environment: Create environment with base_url variable
Manual Setup
 1. Create Collection: New → Collection → Name: "FHIR Explorer" 2. Add Environment: Environments → Add → Name: "FHIR Explorer" 3. Environment Variables:    - base_url: https://your-deployment-url.com     - api_version: v1
Collection Requests
1. Analyze Practitioner - Method: GET - URL: {{base_url}}/api/{{api_version}}/analyze/Practitioner - Params Tab:   - specification: generic-r4   - filter: all    - validations: true   - nested: true
2. Analyze Patient (US Core) - Method: GET - URL: {{base_url}}/api/{{api_version}}/analyze/Patient - Params Tab:   - specification: us-core   - filter: important   - validations: true
3. Test All Resources - Method: GET - URL: {{base_url}}/api/{{api_version}}/resources
4. Health Status - Method: GET - URL: {{base_url}}/health
Pre-request Scripts (Optional)
 Add to collection or individual requests for debugging:
javascript console.log("Calling FHIR Explorer API:", pm.request.url); console.log("Timestamp:", new Date().toISOString()); 
 
Tests Scripts (Optional)
 Add to requests for validation:
javascript pm.test("Status code is 200", function () { pm.response.to.have.status(200); });

pm.test("Response has resourceType", function () { const jsonData = pm.response.json(); pm.expect(jsonData).to.have.property('resourceType'); });

pm.test("Response time is acceptable", function () { pm.expect(pm.response.responseTime).to.be.below(5000); }); 

 
Key Features
Clinical Identifier Validation
The API enforces clinical appropriateness for identifier types:
Practitioner Identifiers: - ✅ NPI (National Provider Identifier) - ✅ SL (State License Number)  - ✅ TAX (Tax ID Number) - ❌ MR (Medical Record Number) - inappropriate - ❌ SSN (Social Security Number) - inappropriate
Patient Identifiers: - ✅ MR (Medical Record Number) - ✅ SSN (Social Security Number) - ✅ MC (Medicare Number) - ✅ MA (Medicaid Number) - ❌ NPI (National Provider Identifier) - inappropriate - ❌ DEA (Drug Enforcement Administration Number) - inappropriate
Format Validation
Identifiers include regex patterns and specialized validation:
- NPI: 10-digit with Luhn check digit validation - DEA: Format validation with check digit algorithm - Tax ID: Federal format NN-NNNNNNN - Medicare: Part A/B format validation - SSN: Standard format with area/group/serial validation
MoSCoW Priority Levels
Fields are tagged with implementation priority: - Must: Critical for basic functionality - Should: Important for production use - Could: Enhanced functionality - Won't: Not recommended for current implementation
Error Responses
Standard Error Format
json { "code": "string", "httpStatus": "number", "message": "string", "details": ["string"] } 
 
Common Error Codes
 
 Status Code Description 
 
 400 INVALID_RESOURCE Resource type not supported 
 
 400 INVALID_PARAMETER Invalid query parameter value 
 
 404 STRUCTURE_NOT_FOUND StructureDefinition not available 
 
 429 RATE_LIMIT_EXCEEDED Too many requests 
 
 503 SERVICE_UNAVAILABLE Backend service starting up 
 
Postman Collection Import
You can import this collection into Postman:
json { "info": { "name": "FHIR Explorer API", "description": "AI-optimized FHIR structure analysis with clinical identifier validation", "version": "1.2.0" }, "variable": [ { "key": "base_url", "value": "https://your-deployment-url.com", "type": "string" } ], "item": [ { "name": "Analyze Practitioner", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/analyze/Practitioner?specification=generic-r4&filter=all&validations=true&nested=true", "host": ["{{base_url}}"], "path": ["api", "v1", "analyze", "Practitioner"], "query": [ {"key": "specification", "value": "generic-r4"}, {"key": "filter", "value": "all"}, {"key": "validations", "value": "true"}, {"key": "nested", "value": "true"} ] } } }, { "name": "Analyze Patient (US Core)", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/analyze/Patient?specification=us-core&filter=important&validations=true", "host": ["{{base_url}}"], "path": ["api", "v1", "analyze", "Patient"], "query": [ {"key": "specification", "value": "us-core"}, {"key": "filter", "value": "important"}, {"key": "validations", "value": "true"} ] } } }, { "name": "List Supported Resources", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/api/v1/resources", "host": ["{{base_url}}"], "path": ["api", "v1", "resources"] } } }, { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{base_url}}/health", "host": ["{{base_url}}"], "path": ["health"] } } } ] } ``

Use Cases

EMR Form Building

Use the analyze endpoint to generate dynamic forms:

1. Get field structure: Call /api/v1/analyze/Patient?filter=important 2. Build UI components: Use uiHint for component selection 3. Validate input: Apply validations rules 4. Populate dropdowns: Use binding.options for select fields 5. Enforce clinical rules: Respect identifier type restrictions

Clinical Data Validation

Validate FHIR resources before submission:

1. Schema validation: Use field requirements and cardinality 2. Identifier validation: Apply format patterns and clinical appropriateness 3. Reference validation: Check referenceTarget for valid references 4. ValueSet compliance: Validate against binding.options`

Integration Testing

Test FHIR implementations:

1. Structure compliance: Verify all required fields are present 2. Identifier formats: Test with various identifier types 3. Clinical appropriateness: Ensure proper identifier usage 4. Extension support: Validate custom extensions

Support

For issues or questions: - Check the health endpoint for system status - Verify rate limits in response headers - Review error responses for specific guidance - All identifier validation follows HL7 FHIR R4 and US Core specifications

Version Information

- API Version: 1.2.0 - FHIR Version: R4 (4.0.1) - US Core Version: Latest available - Last Updated: June 2025