# FHIR Server Extractor (`datamule/fhir-server-extractor`) Actor Point at ANY HL7 FHIR R4 server (HAPI, SMART-on-FHIR, Azure/Google/AWS health APIs) and page any resource type (Patient, Observation, Condition, Encounter) into clean flat rows. Follows the Bundle next-link cursor, keeps the full resource in \_raw. Discovery mode maps a server. Pay per record. - **URL**: https://apify.com/datamule/fhir-server-extractor.md - **Developed by:** [Datamule](https://apify.com/datamule) (community) - **Categories:** Developer tools, Business - **Stats:** 2 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.35 / 1,000 resources This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README **FHIR Server Extractor** reads authorized HL7 FHIR R4 JSON endpoints, follows their `Bundle` next-link cursors, and emits one stable dataset row per matched resource. Use `search` mode to export resources or `capabilities` mode to inspect the resource types and search parameters a server advertises. ### Try it now This ready-to-run input requests up to 25 Patient resources from the public HAPI FHIR reference sandbox. HAPI is a shared test service, so its contents and availability can change. The records in this environment are synthetic test data, not production patient records. ```json { "sources": ["https://hapi.fhir.org/baseR4"], "mode": "search", "resourceTypes": ["Patient"], "maxRecords": 25 } ```` 1. Paste the JSON into the Actor's **Input** tab. 2. Select **Start**. 3. Open the default dataset to inspect or export the rows. The same input can be sent through the Apify API, used in a scheduled task, or connected to an Apify integration. You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. ### Representative output #### SYNTHETIC Patient sample The row below is generated from the retained HAPI fixture used by this Actor's local regression tests. It shows the exact stable row shape, including the source resource preserved in `_raw`. **This is not a real patient record.** ```json { "_sourceServer": "https://hapi.fhir.org/baseR4", "_resourceType": "Patient", "_fhirVersion": "4.0.1", "_serverSoftware": "HAPI FHIR", "_mode": "search", "_searchUrl": "https://hapi.fhir.org/baseR4/Patient?_count=25", "resourceType": "Patient", "id": "131896579", "lastUpdated": "2026-04-10T15:55:37.648+00:00", "meta_versionId": "1", "meta_source": "#1SvhmbQgtkfxewf0", "meta_profile": null, "status": null, "display": "Carlos Ramirez", "supported_interactions": null, "supported_search_params": null, "software_name": null, "software_version": null, "_raw": { "resourceType": "Patient", "id": "131896579", "meta": { "versionId": "1", "lastUpdated": "2026-04-10T15:55:37.648+00:00", "source": "#1SvhmbQgtkfxewf0" }, "identifier": [ { "system": "urn:oid:1.2.36", "value": "12345" } ], "name": [ { "use": "official", "family": "Ramirez", "given": ["Carlos"] } ], "gender": "male", "birthDate": "1975-03-02" } } ``` Fields that do not apply to the selected mode or resource are `null`; the Actor does not invent replacements. ### How much does FHIR extraction cost? The pay-per-event event is `resource`: $0.0005 per emitted resource. The default 25-row ceiling is $0.0125. The rate is $0.50 per 1,000 emitted resources. A run that emits fewer rows costs less; a valid zero-result run emits no billable resource events. Apify infrastructure/compute charges are separate and may apply. | Emitted resources | Resource-event charge | |---:|---:| | 0 | $0.00 | | 25 | $0.0125 | | 1,000 | $0.50 | ### Inputs, defaults, and limits `maxRecords` defaults to `25`. The minimum is `1`, and an explicit larger integer remains supported when a broader export is intentional. The cap applies across all sources and resource types in the run, not separately to each combination. | Field | Required | Default or prefill | Meaning and limits | |---|---|---|---| | `sources` | Yes | HAPI URL prefilled | One or more FHIR R4 base URLs. Use the base/root, not `/Patient` or `/metadata`. | | `mode` | No | `search` | `search` emits matched resources. `capabilities` reads `/metadata` and emits advertised resource types. | | `resourceTypes` | No | `["Patient"]` | UpperCamelCase FHIR resource types. Used only in `search` mode. | | `searchParams` | No | Empty | A JSON object applied to each requested resource type. `_count` is managed by the Actor. Parameter support is server- and resource-specific. | | `maxRecords` | No | `25` | Total emitted-row ceiling across the run. Minimum `1`; set a larger value explicitly to override the trial cap. | | `bearerToken` | No | Empty | OAuth2 bearer token for an already-authorized server. The Actor does not perform an OAuth login or token exchange. | | `extraHeaders` | No | Empty | Additional request headers required by the server, such as a client identifier. | The Actor requests pages of up to 50 resources, follows each absolute `link[relation=next]` URL as returned, and stops at `maxRecords`. Source-side page limits, timeouts, authorization rules, Apify run limits, and a hard pagination safety guard still apply. ### Output field dictionary Both modes use the same stable set of columns. Search-only columns are `null` on capability rows, and capability-only columns are `null` on search rows. | Field | Meaning | |---|---| | `_sourceServer` | FHIR base URL that produced the row. | | `_resourceType` | Requested or advertised resource type used for provenance. | | `_fhirVersion` | Version reported by the server's `CapabilityStatement`, when available. | | `_serverSoftware` | Best-effort software-family label, when detectable. | | `_mode` | `search` or `capabilities`. | | `_searchUrl` | Exact page URL that produced a search row; `null` in capabilities mode. | | `resourceType` | FHIR resource type represented by the row. | | `id` | FHIR logical ID; `null` for capability rows. | | `lastUpdated` | Resource `meta.lastUpdated` supplied by the server; may be `null`. | | `meta_versionId` | Resource `meta.versionId`, when supplied. | | `meta_source` | Resource `meta.source`, when supplied. | | `meta_profile` | Resource `meta.profile` canonical URLs, when supplied. | | `status` | Top-level resource status, when that resource type has one. | | `display` | Best-effort label from a name, title, or code display. | | `supported_interactions` | Capability row's advertised interaction codes. | | `supported_search_params` | Capability row's advertised search-parameter names. | | `software_name` | CapabilityStatement software name. | | `software_version` | CapabilityStatement software version. | | `_raw` | Original resource or capability-resource object, capped for row-size safety. | ### Common use cases - Export a bounded, authorized FHIR R4 resource set for analysis or QA. - Inspect a server's advertised resource types and search surface before an integration is built. - Schedule an incremental extract with a supported `_lastUpdated` filter. - Compare normalized provenance fields across conformant R4 test or vendor endpoints while retaining each original resource in `_raw`. ### Coverage, observation time, and freshness The generic scope is **FHIR R4 JSON**: search responses shaped as FHIR `Bundle` resources and capability discovery through `/metadata`. It does not claim FHIR R5 support, Bulk Data `$export`, subscriptions, GraphQL, terminology expansion, or create/update/delete operations. Vendor profiles, supported resource types, search parameters, paging behavior, and authorization requirements vary even when the transport is R4-conformant. HAPI FHIR and SMART-on-FHIR / Logica are public sandboxes containing synthetic test data. They demonstrate the common R4 grammar; they do not prove that a private vendor endpoint will allow the same searches or be available at the time of your run. Each run is a bounded observation of what the server returned at that time: - `lastUpdated` is the server's resource-version timestamp, not the extraction time, and it may be absent. - The dataset deliberately has no invented observation timestamp. Use the Apify run start/finish metadata as the observation window. - The Actor does not impose a sort order. With `maxRecords: 25`, it keeps the first 25 matched rows in the server's response order, so the sample is not a completeness guarantee. - For incremental collection, schedule runs and pass a server-supported `_lastUpdated` search value. Deduplicate by source, resource type, logical ID, and version according to your own retention policy. - A capabilities row reflects the `/metadata` response observed during that run; server capabilities can change later. ### Privacy and authorization limits Use this Actor only with endpoints and data you are authorized to read. FHIR resources can contain protected health information. `_raw` retains the source resource, so downstream datasets and exports require the same access controls as the source data. `bearerToken` is a secret input and is not intentionally logged. Treat `extraHeaders`, task inputs, datasets, and exported files as sensitive whenever they contain credentials or health data. Prefer private tasks and appropriate Apify security controls for non-public systems. This extraction utility does not grant permission, acquire consent, or by itself establish HIPAA or other regulatory compliance. ### Troubleshooting #### Wrong base URL Supply the FHIR base/root, such as `https://hapi.fhir.org/baseR4`. Do not append a resource type or `/metadata`; the Actor adds those paths. A wrong base commonly produces HTTP 404, a non-JSON page, or “expected Bundle/CapabilityStatement.” #### Authentication HTTP 401 or 403 means the server did not accept the request. Provide a current `bearerToken` and any required `extraHeaders`, then confirm the token scopes permit the requested resource type and search. The Actor accepts an existing token but does not run a vendor OAuth flow. #### `OperationOutcome` FHIR can return an `OperationOutcome` even with HTTP 200. The Actor treats a top-level outcome as an error rather than an empty result and reports the first issue's severity, code, and diagnostics. Remove or correct unsupported `searchParams`; if every source fails, the run exits non-zero instead of presenting a false successful empty dataset. #### Zero results A valid search `Bundle` with no matching entries is a successful zero-result run. Check the resource type's exact casing, remove filters, confirm the server actually advertises the type with `mode: "capabilities"`, and verify that your authorization permits matches. Included companions and outcome entries are filtered deliberately; only genuine matches are emitted. For support, use the Actor's **Issues** tab with the base URL, mode, resource types, non-sensitive search parameters, and the relevant error text. Never post tokens, authorization headers, or patient data. # Actor input Schema ## `sources` (type: `array`): One or more HL7 FHIR R4 base/root URLs. Examples: https://hapi.fhir.org/baseR4 (HAPI reference server) and https://r4.smarthealthit.org (SMART-on-FHIR / Logica sandbox — both synthetic test data). Point at the FHIR BASE — do NOT append a resource type or /metadata. ## `mode` (type: `string`): What to extract. "search" (default): page each resource type and emit one flat row per matched FHIR resource (id, lastUpdated, status, display, provenance, and the full resource in \_raw). "capabilities": GET the server's /metadata CapabilityStatement and emit one row per resource type it advertises (supported interactions, search params, FHIR version, software) — a discovery map of a server. ## `resourceTypes` (type: `array`): FHIR resource type(s) to search (used by "search" mode), e.g. Patient, Observation, Condition, Encounter, Organization, Practitioner, MedicationRequest. UpperCamelCase, as defined by FHIR R4. Defaults to \["Patient"]. Ignored in "capabilities" mode. ## `searchParams` (type: `object`): Optional FHIR search parameters applied to every resource type, as a JSON object. Examples: {"\_lastUpdated": "gt2024-01-01"} for records changed since a date, {"gender": "female"} for Patient, {"status": "final"} for Observation. The paging \_count is managed for you. Leave empty to fetch everything (bounded by Max records). ## `maxRecords` (type: `integer`): Maximum total number of rows to emit across all sources and resource types. The next-link cursor is followed until this cap is reached, so a huge server never runs forever. Each returned row is one billable event. Default 25; set any integer of 1 or more to override the cap explicitly. ## `bearerToken` (type: `string`): Optional OAuth2 bearer token for auth-gated FHIR servers. Sent as Authorization: Bearer \*\*\*. NOT required for public sandboxes (HAPI, SMART) — leave empty. Never logged. ## `extraHeaders` (type: `object`): Optional extra HTTP headers to send with every request, as a JSON object, e.g. {"Epic-Client-ID": "..."} for a vendor that requires a header. Leave empty for public servers. ## Actor input object example ```json { "sources": [ "https://hapi.fhir.org/baseR4" ], "mode": "search", "resourceTypes": [ "Patient" ], "maxRecords": 25 } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "sources": [ "https://hapi.fhir.org/baseR4" ], "resourceTypes": [ "Patient" ], "maxRecords": 25 }; // Run the Actor and wait for it to finish const run = await client.actor("datamule/fhir-server-extractor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "sources": ["https://hapi.fhir.org/baseR4"], "resourceTypes": ["Patient"], "maxRecords": 25, } # Run the Actor and wait for it to finish run = client.actor("datamule/fhir-server-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "sources": [ "https://hapi.fhir.org/baseR4" ], "resourceTypes": [ "Patient" ], "maxRecords": 25 }' | apify call datamule/fhir-server-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datamule/fhir-server-extractor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "FHIR Server Extractor", "description": "Point at ANY HL7 FHIR R4 server (HAPI, SMART-on-FHIR, Azure/Google/AWS health APIs) and page any resource type (Patient, Observation, Condition, Encounter) into clean flat rows. Follows the Bundle next-link cursor, keeps the full resource in _raw. Discovery mode maps a server. Pay per record.", "version": "0.1", "x-build-id": "f2VP3wfQVnx9nRmv8" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamule~fhir-server-extractor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamule-fhir-server-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/datamule~fhir-server-extractor/runs": { "post": { "operationId": "runs-sync-datamule-fhir-server-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/datamule~fhir-server-extractor/run-sync": { "post": { "operationId": "run-sync-datamule-fhir-server-extractor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "title": "FHIR R4 base URL(s)", "type": "array", "description": "One or more HL7 FHIR R4 base/root URLs. Examples: https://hapi.fhir.org/baseR4 (HAPI reference server) and https://r4.smarthealthit.org (SMART-on-FHIR / Logica sandbox — both synthetic test data). Point at the FHIR BASE — do NOT append a resource type or /metadata.", "items": { "type": "string" } }, "mode": { "title": "Mode", "enum": [ "search", "capabilities" ], "type": "string", "description": "What to extract. \"search\" (default): page each resource type and emit one flat row per matched FHIR resource (id, lastUpdated, status, display, provenance, and the full resource in _raw). \"capabilities\": GET the server's /metadata CapabilityStatement and emit one row per resource type it advertises (supported interactions, search params, FHIR version, software) — a discovery map of a server.", "default": "search" }, "resourceTypes": { "title": "Resource type(s)", "type": "array", "description": "FHIR resource type(s) to search (used by \"search\" mode), e.g. Patient, Observation, Condition, Encounter, Organization, Practitioner, MedicationRequest. UpperCamelCase, as defined by FHIR R4. Defaults to [\"Patient\"]. Ignored in \"capabilities\" mode.", "items": { "type": "string" } }, "searchParams": { "title": "Search parameters (optional)", "type": "object", "description": "Optional FHIR search parameters applied to every resource type, as a JSON object. Examples: {\"_lastUpdated\": \"gt2024-01-01\"} for records changed since a date, {\"gender\": \"female\"} for Patient, {\"status\": \"final\"} for Observation. The paging _count is managed for you. Leave empty to fetch everything (bounded by Max records)." }, "maxRecords": { "title": "Max records (total)", "minimum": 1, "type": "integer", "description": "Maximum total number of rows to emit across all sources and resource types. The next-link cursor is followed until this cap is reached, so a huge server never runs forever. Each returned row is one billable event. Default 25; set any integer of 1 or more to override the cap explicitly.", "default": 25 }, "bearerToken": { "title": "Bearer token (optional)", "type": "string", "description": "Optional OAuth2 bearer token for auth-gated FHIR servers. Sent as Authorization: Bearer ***. NOT required for public sandboxes (HAPI, SMART) — leave empty. Never logged." }, "extraHeaders": { "title": "Extra request headers", "type": "object", "description": "Optional extra HTTP headers to send with every request, as a JSON object, e.g. {\"Epic-Client-ID\": \"...\"} for a vendor that requires a header. Leave empty for public servers." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```