Medplum Elixir

Elixir client for Medplum's FHIR API.

Built for apps that want:

direct CRUD on FHIR resources
resource-specific helpers under Medplum.Resources.*
workflow helpers under Medplum.Workflows.*
token reuse across requests
stable {:error, %Medplum.Error{}} returns
lower-level escape hatches for operations, batch, transaction, binary, upsert, GraphQL, and raw requests

Installation

Add package to mix.exs:

def deps do
  [
    {:medplum_elixir, "~> 0.2.0"}
  ]
end

Then fetch deps:

mix deps.get

Quick start

Medplum uses OAuth client credentials. Set env vars first:

export MEDPLUM_BASE_URL="https://api.medplum.com"
export MEDPLUM_CLIENT_ID="..."
export MEDPLUM_CLIENT_SECRET="..."

Create reusable client:

client =
  Medplum.new(
    base_url: System.fetch_env!("MEDPLUM_BASE_URL"),
    client_id: System.fetch_env!("MEDPLUM_CLIENT_ID"),
    client_secret: System.fetch_env!("MEDPLUM_CLIENT_SECRET")
  )

Read resource:

{:ok, patient} = Medplum.read(client, "Patient", "123")

Search resource:

{:ok, bundle} = Medplum.search(client, "Patient", %{"family" => "Smith"})

Patch resource:

ops = [%{"op" => "replace", "path" => "/active", "value" => true}]
{:ok, patient} = Medplum.patch(client, "Patient", "123", ops)

Stream paged search results:

entries =
  client
  |> Medplum.stream_search("Patient", %{"family" => "Smith"})
  |> Enum.to_list()

Client options

Medplum.new/1 accepts:

base_url - Medplum server URL, trailing slash removed automatically
client_id - OAuth client id
client_secret - OAuth client secret
fhir_version - defaults to "R4"
default_headers - merged into every request
req_options - forwarded to Req
auth_req_options - forwarded only to token requests
retry - false, :safe_transient, or :transient
max_retries - defaults to 2
token_refresh_skew - defaults to 60
cache_tokens - defaults to true

Example with request tuning:

client =
  Medplum.new(
    base_url: System.fetch_env!("MEDPLUM_BASE_URL"),
    client_id: System.fetch_env!("MEDPLUM_CLIENT_ID"),
    client_secret: System.fetch_env!("MEDPLUM_CLIENT_SECRET"),
    default_headers: [{"x-app-name", "my_app"}],
    req_options: [receive_timeout: 15_000],
    max_retries: 2,
    token_refresh_skew: 60
  )

Core API

Main module covers generic FHIR and Medplum operations:

read/3
search/3
create/3
update/4
delete/3
patch/4
request/4
operation/5
poll_async/3
batch/2
transaction/2
create_binary/3
get_binary/2
upsert/3
graphql/3
stream_search/3

Example:

{:ok, bundle} =
  Medplum.batch(client, [
    %{"request" => %{"method" => "GET", "url" => "Patient/123"}}
  ])

{:ok, graphql_result} =
  Medplum.graphql(client, "query Demo { PatientList { id } }")

Resource helpers

Thin wrappers live under Medplum.Resources.*.

Common modules:

Patient
Appointment
Encounter
Task
Observation
Condition
DocumentReference
ServiceRequest
DiagnosticReport
Claim
Coverage
Organization
Practitioner
PractitionerRole
Schedule
Slot
Location
Bot
Subscription

Example:

alias Medplum.Resources.Patient
alias Medplum.Resources.Task

{:ok, patient} = Patient.get(client, "123")

{:ok, matches} =
  Patient.search_by_identifier(client, "http://hospital.example/mrn", "123")

{:ok, tasks} =
  Task.search_by_owner(client, "Practitioner/dr-1", %{"status" => "requested"})

Many resource modules also expose identifier-based upsert helpers:

{:ok, patient} =
  Patient.upsert(client, %{
    "identifier" => [%{"system" => "http://hospital.example/mrn", "value" => "123"}],
    "name" => [%{"family" => "Smith"}]
  })

Workflow helpers

Higher-level modules live under Medplum.Workflows.*.

Available workflows:

Scheduling
Billing
Automation
Medications
CareCoordination
CarePlanning
Tasks
Intake
Orders
Charting

Example:

alias Medplum.Workflows.Automation
alias Medplum.Workflows.Billing
alias Medplum.Workflows.CarePlanning
alias Medplum.Workflows.CareCoordination
alias Medplum.Workflows.Charting
alias Medplum.Workflows.Intake
alias Medplum.Workflows.Medications
alias Medplum.Workflows.Orders
alias Medplum.Workflows.Scheduling
alias Medplum.Workflows.Tasks

{:ok, open_tasks} =
  Tasks.list_for_owner(client, "Practitioner/dr-1", %{"status" => "requested"})

{:ok, appointments} =
  Scheduling.find_appointments(client, %{
    "resourceType" => "Parameters",
    "parameter" => [%{"name" => "start", "valueDateTime" => "2026-07-04T09:00:00Z"}]
  })

{:ok, service_requests} =
  Orders.service_requests_for_subject(client, "Patient/123")

{:ok, claim_pdf} =
  Billing.export_claim(client, "claim-123")

{:ok, bot_result} =
  Automation.execute_bot(client, "bot-123", %{
    "resourceType" => "Patient",
    "id" => "123"
  })

{:ok, active_meds} =
  Medications.active_medication_requests_for_subject(client, "Patient/123")

{:ok, care_goals} =
  CarePlanning.active_goals_for_subject(client, "Patient/123")

{:ok, family_contacts} =
  CareCoordination.active_family_for_patient(client, "Patient/123")

{:ok, observations} =
  Charting.observations_for_patient(client, "Patient/123", %{"category" => "vital-signs"})

{:ok, responses} =
  Intake.questionnaire_responses_for_subject(client, "Patient/123")

Error handling

All public functions return either success tuple or %Medplum.Error{}:

case Medplum.read(client, "Patient", "missing-id") do
  {:ok, patient} ->
    patient

  {:error, %Medplum.Error{type: :api_error, status: 404}} ->
    nil

  {:error, %Medplum.Error{} = error} ->
    raise error
end

Error types:

:config_error
:auth_failed
:request_failed
:api_error
:invalid_response

Phoenix config

# config/runtime.exs
config :my_app, :medplum,
  base_url: System.fetch_env!("MEDPLUM_BASE_URL"),
  client_id: System.fetch_env!("MEDPLUM_CLIENT_ID"),
  client_secret: System.fetch_env!("MEDPLUM_CLIENT_SECRET")

client =
  :my_app
  |> Application.fetch_env!(:medplum)
  |> Medplum.new()

Docs

API docs generated with mix docs
ExDoc extras:
- README.md
- guides/getting-started.md
- guides/resource-and-workflow-helpers.md

Development

Run tests:

mix test

Build docs:

mix docs

Next Page → Getting Started