Skip to main content

Class: MedplumClient

The MedplumClient class provides a client for the Medplum FHIR server.

The client can be used in the browser, in a NodeJS application, or in a Medplum Bot.

The client provides helpful methods for common operations such as: 1) Authenticating 2) Creating resources 2) Reading resources 3) Updating resources 5) Deleting resources 6) Searching 7) Making GraphQL queries

Here is a quick example of how to use the client:

import { MedplumClient } from '@medplum/core';
const medplum = new MedplumClient();

Create a Patient:

const patient = await medplum.createResource({
resourceType: 'Patient',
name: [{
given: ['Alice'],
family: 'Smith'
}]
});

Read a Patient by ID:

const patient = await medplum.readResource('Patient', '123');
console.log(patient.name[0].given[0]);

Search for a Patient by name:

const bundle = await medplum.search('Patient?name=Alice');
console.log(bundle.total);

Hierarchy

  • EventTarget

    MedplumClient

Constructors

constructor

new MedplumClient(options?)

Parameters

NameType
options?MedplumClientOptions

Overrides

EventTarget.constructor

Defined in

packages/core/src/client.ts:233

Methods

addEventListener

addEventListener(type, callback): void

Parameters

NameType
typestring
callbackEventListener

Returns

void

Inherited from

EventTarget.addEventListener

Defined in

packages/core/src/eventtarget.ts:19


clear

clear(): void

Clears all auth state including local storage and session storage.

Returns

void

Defined in

packages/core/src/client.ts:269


clientCredentials

clientCredentials(clientId, clientSecret): Promise<ProfileResource>

Parameters

NameType
clientIdstring
clientSecretstring

Returns

Promise<ProfileResource>

Defined in

packages/core/src/client.ts:1380


createBinary

createBinary(data, filename, contentType): Promise<Binary>

Creates a FHIR Binary resource with the provided data content.

The return value is the newly created resource, including the ID and meta.

The data parameter can be a string or a File object.

A File object often comes from a <input type="file"> element.

Example:

const result = await medplum.createBinary(myFile, 'test.jpg', 'image/jpeg');
console.log(result.id);

See the FHIR "create" operation for full details: https://www.hl7.org/fhir/http.html#create

Parameters

NameTypeDescription
datastring | FileThe binary data to upload.
filenameundefined | stringOptional filename for the binary.
contentTypestringContent type for the binary.

Returns

Promise<Binary>

The result of the create operation.

Defined in

packages/core/src/client.ts:925


createPdf

createPdf(docDefinition, filename?): Promise<Binary>

Creates a PDF as a FHIR Binary resource based on pdfmake document definition.

The return value is the newly created resource, including the ID and meta.

The docDefinition parameter is a pdfmake document definition.

Example:

const result = await medplum.createPdf({
content: ['Hello world']
});
console.log(result.id);

See the pdfmake document definition for full details: https://pdfmake.github.io/docs/0.1/document-definition-object/

Parameters

NameTypeDescription
docDefinitionRecord<string, unknown>The FHIR resource to create.
filename?string-

Returns

Promise<Binary>

The result of the create operation.

Defined in

packages/core/src/client.ts:954


createResource

createResource<T>(resource): Promise<T>

Creates a new FHIR resource.

The return value is the newly created resource, including the ID and meta.

Example:

const result = await medplum.createResource({
resourceType: 'Patient',
name: [{
family: 'Smith',
given: ['John']
}]
});
console.log(result.id);

See the FHIR "create" operation for full details: https://www.hl7.org/fhir/http.html#create

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTThe FHIR resource to create.

Returns

Promise<T>

The result of the create operation.

Defined in

packages/core/src/client.ts:853


createResourceIfNoneExist

createResourceIfNoneExist<T>(resource, query): Promise<T>

Conditionally create a new FHIR resource only if some equivalent resource does not already exist on the server.

The return value is the existing resource or the newly created resource, including the ID and meta.

Example:

const result = await medplum.createResourceIfNoneExist(
'Patient?identifier=123',
{
resourceType: 'Patient',
identifier: [{
system: 'http://example.com/mrn',
value: '123'
}]
name: [{
family: 'Smith',
given: ['John']
}]
});
console.log(result.id);

This method is syntactic sugar for:

return searchOne(query) ?? createResource(resource);

The query parameter only contains the search parameters (what would be in the URL following the "?").

See the FHIR "conditional create" operation for full details: https://www.hl7.org/fhir/http.html#ccreate

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTThe FHIR resource to create.
querystringThe search query for an equivalent resource.

Returns

Promise<T>

The result of the create operation.

Defined in

packages/core/src/client.ts:898


delete

delete(url, options?): Promise<any>

Makes an HTTP DELETE request to the specified URL.

This is a lower level method for custom requests. For common operations, we recommend using higher level methods such as deleteResource().

Parameters

NameTypeDescription
urlstringThe target URL.
optionsRequestInitOptional fetch options.

Returns

Promise<any>

Promise to the response content.

Defined in

packages/core/src/client.ts:380


deleteResource

deleteResource(resourceType, id): Promise<any>

Deletes a FHIR resource by resource type and ID.

Example:

await medplum.deleteResource('Patient', '123');

See the FHIR "delete" operation for full details: https://www.hl7.org/fhir/http.html#delete

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.
idstringThe resource ID.

Returns

Promise<any>

The result of the delete operation.

Defined in

packages/core/src/client.ts:1038


dispatchEvent

dispatchEvent(event): boolean

Parameters

NameType
eventEvent

Returns

boolean

Inherited from

EventTarget.dispatchEvent

Defined in

packages/core/src/eventtarget.ts:39


download

download(url, options?): Promise<Blob>

Downloads the URL as a blob.

Parameters

NameTypeDescription
urlstringThe URL to request.
optionsRequestInit-

Returns

Promise<Blob>

Promise to the response body as a blob.

Defined in

packages/core/src/client.ts:1160


fhirUrl

fhirUrl(...path): string

Builds a FHIR URL from a collection of URL path components. For example, buildUrl('/Patient', '123') returns fhir/R4/Patient/123.

Parameters

NameTypeDescription
...pathstring[]The path component of the URL.

Returns

string

The well-formed FHIR URL.

Defined in

packages/core/src/client.ts:462


get

get<T>(url, options?): ReadablePromise<T>

Makes an HTTP GET request to the specified URL.

This is a lower level method for custom requests. For common operations, we recommend using higher level methods such as readResource(), search(), etc.

Type parameters

NameType
Tany

Parameters

NameTypeDescription
urlstringThe target URL.
optionsRequestInitOptional fetch options.

Returns

ReadablePromise<T>

Promise to the response content.

Defined in

packages/core/src/client.ts:290


getActiveLogin

getActiveLogin(): undefined | LoginState

Returns

undefined | LoginState

Defined in

packages/core/src/client.ts:1087


getCached

getCached<T>(resourceType, id): undefined | T

Returns a cached resource if it is available.

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.
idstringThe FHIR resource ID.

Returns

undefined | T

The resource if it is available in the cache; undefined otherwise.

Defined in

packages/core/src/client.ts:604


getCachedReference

getCachedReference<T>(reference): undefined | T

Returns a cached resource if it is available.

Type parameters

NameType
Textends Resource

Parameters

NameType
referenceReference<T>

Returns

undefined | T

The resource if it is available in the cache; undefined otherwise.

Defined in

packages/core/src/client.ts:615


getLogins

getLogins(): LoginState[]

Returns

LoginState[]

Defined in

packages/core/src/client.ts:1110


getProfile

getProfile(): undefined | ProfileResource

Returns

undefined | ProfileResource

Defined in

packages/core/src/client.ts:1140


getProfileAsync

getProfileAsync(): Promise<undefined | ProfileResource>

Returns

Promise<undefined | ProfileResource>

Defined in

packages/core/src/client.ts:1144


getSchema

getSchema(): IndexedStructureDefinition

Returns a cached schema for a resource type. If the schema is not cached, returns undefined. It is assumed that a client will call requestSchema before using this method.

Returns

IndexedStructureDefinition

The schema if immediately available, undefined otherwise.

Defined in

packages/core/src/client.ts:726


getUserConfiguration

getUserConfiguration(): undefined | UserConfiguration

Returns

undefined | UserConfiguration

Defined in

packages/core/src/client.ts:1151


graphql

graphql(query, options?): Promise<any>

Parameters

NameType
querystring
options?RequestInit

Returns

Promise<any>

Defined in

packages/core/src/client.ts:1083


isLoading

isLoading(): boolean

Returns

boolean

Defined in

packages/core/src/client.ts:1136


patch

patch(url, operations, options?): Promise<any>

Makes an HTTP PATCH request to the specified URL.

This is a lower level method for custom requests. For common operations, we recommend using higher level methods such as patchResource().

Parameters

NameTypeDescription
urlstringThe target URL.
operationsOperation[]Array of JSONPatch operations.
optionsRequestInitOptional fetch options.

Returns

Promise<any>

Promise to the response content.

Defined in

packages/core/src/client.ts:362


patchResource

patchResource<T>(resourceType, id, operations): Promise<T>

Updates a FHIR resource using JSONPatch operations.

The return value is the updated resource, including the ID and meta.

Example:

const result = await medplum.patchResource('Patient', '123', [
{op: 'replace', path: '/name/0/family', value: 'Smith'},
]);
console.log(result.meta.versionId);

See the FHIR "update" operation for full details: https://www.hl7.org/fhir/http.html#patch

See the JSONPatch specification for full details: https://tools.ietf.org/html/rfc6902

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.
idstringThe resource ID.
operationsOperation[]The JSONPatch operations.

Returns

Promise<T>

The result of the patch operations.

Defined in

packages/core/src/client.ts:1019


post

post(url, body, contentType?, options?): Promise<any>

Makes an HTTP POST request to the specified URL.

This is a lower level method for custom requests. For common operations, we recommend using higher level methods such as createResource().

Parameters

NameTypeDescription
urlstringThe target URL.
bodyanyThe content body. Strings and File objects are passed directly. Other objects are converted to JSON.
contentType?stringThe content type to be included in the "Content-Type" header.
optionsRequestInitOptional fetch options.

Returns

Promise<any>

Promise to the response content.

Defined in

packages/core/src/client.ts:315


processCode

processCode(code): Promise<ProfileResource>

Processes an OAuth authorization code. See: https://openid.net/specs/openid-connect-core-1_0.html#TokenRequest

Parameters

NameTypeDescription
codestringThe authorization code received by URL parameter.

Returns

Promise<ProfileResource>

Defined in

packages/core/src/client.ts:1330


put

put(url, body, contentType?, options?): Promise<any>

Makes an HTTP PUT request to the specified URL.

This is a lower level method for custom requests. For common operations, we recommend using higher level methods such as updateResource().

Parameters

NameTypeDescription
urlstringThe target URL.
bodyanyThe content body. Strings and File objects are passed directly. Other objects are converted to JSON.
contentType?stringThe content type to be included in the "Content-Type" header.
optionsRequestInitOptional fetch options.

Returns

Promise<any>

Promise to the response content.

Defined in

packages/core/src/client.ts:339


readCached

readCached<T>(resourceType, id): ReadablePromise<T>

Reads a resource by resource type and ID using the in-memory resource cache.

If the resource is not available in the cache, it will be read from the server.

Example:

const patient = await medplum.readCached('Patient', '123');
console.log(patient);

See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.
idstringThe resource ID.

Returns

ReadablePromise<T>

The resource if available; undefined otherwise.

Defined in

packages/core/src/client.ts:659


readCachedReference

readCachedReference<T>(reference): ReadablePromise<T>

Reads a resource by Reference using the in-memory resource cache.

This is a convenience method for readResource() that accepts a Reference object.

If the resource is not available in the cache, it will be read from the server.

Example:

const serviceRequest = await medplum.readResource('ServiceRequest', '123');
const patient = await medplum.readCachedReference(serviceRequest.subject);
console.log(patient);

See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
referenceReference<T>The FHIR reference object.

Returns

ReadablePromise<T>

The resource if available; undefined otherwise.

Defined in

packages/core/src/client.ts:710


readHistory

readHistory<T>(resourceType, id): Promise<Bundle<T>>

Reads resource history by resource type and ID.

The return value is a bundle of all versions of the resource.

Example:

const history = await medplum.readHistory('Patient', '123');
console.log(history);

See the FHIR "history" operation for full details: https://www.hl7.org/fhir/http.html#history

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.
idstringThe resource ID.

Returns

Promise<Bundle<T>>

The resource if available; undefined otherwise.

Defined in

packages/core/src/client.ts:802


readPatientEverything

readPatientEverything(id): Promise<Bundle<Resource>>

Parameters

NameType
idstring

Returns

Promise<Bundle<Resource>>

Defined in

packages/core/src/client.ts:826


readReference

readReference<T>(reference): ReadablePromise<T>

Reads a resource by Reference.

This is a convenience method for readResource() that accepts a Reference object.

Example:

const serviceRequest = await medplum.readResource('ServiceRequest', '123');
const patient = await medplum.readReference(serviceRequest.subject);
console.log(patient);

See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
referenceReference<T>The FHIR reference object.

Returns

ReadablePromise<T>

The resource if available; undefined otherwise.

Defined in

packages/core/src/client.ts:681


readResource

readResource<T>(resourceType, id): ReadablePromise<T>

Reads a resource by resource type and ID.

Example:

const patient = await medplum.readResource('Patient', '123');
console.log(patient);

See the FHIR "read" operation for full details: https://www.hl7.org/fhir/http.html#read

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.
idstringThe resource ID.

Returns

ReadablePromise<T>

The resource if available; undefined otherwise.

Defined in

packages/core/src/client.ts:637


readVersion

readVersion<T>(resourceType, id, vid): Promise<T>

Reads a specific version of a resource by resource type, ID, and version ID.

Example:

const version = await medplum.readVersion('Patient', '123', '456');
console.log(version);

See the FHIR "vread" operation for full details: https://www.hl7.org/fhir/http.html#vread

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.
idstringThe resource ID.
vidstring-

Returns

Promise<T>

The resource if available; undefined otherwise.

Defined in

packages/core/src/client.ts:822


register

register(request): Promise<void>

Tries to register a new user.

Parameters

NameTypeDescription
requestRegisterRequestThe registration request.

Returns

Promise<void>

Promise to the authentication response.

Defined in

packages/core/src/client.ts:390


removeEventListeneer

removeEventListeneer(type, callback): void

Parameters

NameType
typestring
callbackEventListener

Returns

void

Inherited from

EventTarget.removeEventListeneer

Defined in

packages/core/src/eventtarget.ts:26


requestSchema

requestSchema(resourceType): Promise<IndexedStructureDefinition>

Requests the schema for a resource type. If the schema is already cached, the promise is resolved immediately.

Parameters

NameTypeDescription
resourceTypestringThe FHIR resource type.

Returns

Promise<IndexedStructureDefinition>

Promise to a schema with the requested resource type.

Defined in

packages/core/src/client.ts:736


search<T>(query, options?): Promise<Bundle<T>>

Sends a FHIR search request.

Example using a FHIR search string:

const bundle = await client.search('Patient?name=Alice');
console.log(bundle);

Example using a structured search:

const bundle = await client.search({
resourceType: 'Patient',
filters: [{
code: 'name',
operator: 'eq',
value: 'Alice',
}]
});
console.log(bundle);

The return value is a FHIR bundle:

{
"resourceType": "Bundle",
"type": "searchest",
"total": 1,
"entry": [
{
"resource": {
"resourceType": "Patient",
"name": [
{
"given": [
"George"
],
"family": "Washington"
}
],
}
}
]
}

See FHIR search for full details: https://www.hl7.org/fhir/search.html

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
querystring | SearchRequestThe search query as either a string or a structured search object.
optionsRequestInit-

Returns

Promise<Bundle<T>>

Promise to the search result bundle.

Defined in

packages/core/src/client.ts:522


searchOne

searchOne<T>(query, options?): Promise<undefined | T>

Sends a FHIR search request for a single resource.

This is a convenience method for search() that returns the first resource rather than a Bundle.

Example using a FHIR search string:

const patient = await client.searchOne('Patient?identifier=123');
console.log(patient);

The return value is the resource, if available; otherwise, undefined.

See FHIR search for full details: https://www.hl7.org/fhir/search.html

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
querystring | SearchRequestThe search query as either a string or a structured search object.
optionsRequestInit-

Returns

Promise<undefined | T>

Promise to the search result bundle.

Defined in

packages/core/src/client.ts:548


searchResources

searchResources<T>(query, options?): Promise<T[]>

Sends a FHIR search request for an array of resources.

This is a convenience method for search() that returns the resources as an array rather than a Bundle.

Example using a FHIR search string:

const patients = await client.searchResources('Patient?name=Alice');
console.log(patients);

The return value is an array of resources.

See FHIR search for full details: https://www.hl7.org/fhir/search.html

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
querystring | SearchRequestThe search query as either a string or a structured search object.
optionsRequestInit-

Returns

Promise<T[]>

Promise to the search result bundle.

Defined in

packages/core/src/client.ts:577


searchValueSet

searchValueSet(system, filter, options?): Promise<ValueSet>

Searches a ValueSet resource using the "expand" operation. See: https://www.hl7.org/fhir/operation-valueset-expand.html

Parameters

NameTypeDescription
systemstringThe ValueSet system url.
filterstringThe search string.
optionsRequestInit-

Returns

Promise<ValueSet>

Promise to expanded ValueSet.

Defined in

packages/core/src/client.ts:589


sendEmail

sendEmail(email): Promise<OperationOutcome>

Sends an email using the Medplum Email API.

Builds the email using nodemailer MailComposer.

Examples:

Send a simple text email:

await medplum.sendEmail({
to: 'alice@example.com',
cc: 'bob@example.com',
subject: 'Hello',
text: 'Hello Alice',
});

Send an email with a Binary attachment:

await medplum.sendEmail({
to: 'alice@example.com',
subject: 'Email with attachment',
text: 'See the attached report',
attachments: [{
filename: 'report.pdf',
path: "Binary/" + binary.id
}]
});

See options here: https://nodemailer.com/extras/mailcomposer/

Parameters

NameType
emailOptions

Returns

Promise<OperationOutcome>

Promise to the operation outcome.

Defined in

packages/core/src/client.ts:1079


setAccessToken

setAccessToken(accessToken): void

Parameters

NameType
accessTokenstring

Returns

void

Defined in

packages/core/src/client.ts:1103


setActiveLogin

setActiveLogin(login): Promise<void>

Parameters

NameType
loginLoginState

Returns

Promise<void>

Defined in

packages/core/src/client.ts:1091


signInWithRedirect

signInWithRedirect(): undefined | Promise<void | ProfileResource>

Tries to sign in the user. Returns true if the user is signed in. This may result in navigating away to the sign in page.

Returns

undefined | Promise<void | ProfileResource>

Defined in

packages/core/src/client.ts:437


signOut

signOut(): Promise<void>

Signs out locally. Does not invalidate tokens with the server.

Returns

Promise<void>

Defined in

packages/core/src/client.ts:427


signOutWithRedirect

signOutWithRedirect(): void

Tries to sign out the user. See: https://docs.aws.amazon.com/cognito/latest/developerguide/logout-endpoint.html

Returns

void

Defined in

packages/core/src/client.ts:452


startGoogleLogin

startGoogleLogin(googleResponse): Promise<LoginAuthenticationResponse>

Tries to sign in with Google authentication. The response parameter is the result of a Google authentication. See: https://developers.google.com/identity/gsi/web/guides/handle-credential-responses-js-functions

Parameters

NameTypeDescription
googleResponseGoogleCredentialResponseThe Google credential response.

Returns

Promise<LoginAuthenticationResponse>

Promise to the authentication response.

Defined in

packages/core/src/client.ts:418


startLogin

startLogin(loginRequest): Promise<LoginAuthenticationResponse>

Initiates a user login flow.

Parameters

NameTypeDescription
loginRequestLoginRequestLogin request including email and password.

Returns

Promise<LoginAuthenticationResponse>

Promise to the authentication response.

Defined in

packages/core/src/client.ts:400


updateResource

updateResource<T>(resource): Promise<T>

Updates a FHIR resource.

The return value is the updated resource, including the ID and meta.

Example:

const result = await medplum.updateResource({
resourceType: 'Patient',
id: '123',
name: [{
family: 'Smith',
given: ['John']
}]
});
console.log(result.meta.versionId);

See the FHIR "update" operation for full details: https://www.hl7.org/fhir/http.html#update

Type parameters

NameType
Textends Resource

Parameters

NameTypeDescription
resourceTThe FHIR resource to update.

Returns

Promise<T>

The result of the update operation.

Defined in

packages/core/src/client.ts:986