Updating a resource using PUT - AWS HealthLake

Updating a resource using PUT

The following example shows you how to use PUT to update details about a patient in the patient FHIR resource type. Furthermore, when you make a PUT request on a resource not yet created, it will create an initial version.

You request will return either a 200 HTTP status code if the resource was updated, or it will return a 201 HTTP status code if a new resource was created.


When you make a PUT request on the DocumentReference resource type, the existing extensions are not modified. Instead, AWS HealthLake adds the new extensions with the existing ones to your data store. For more details about how HealthLake uses natural language processing (NLP) on the DocumentReference resource type to extract valuable medical data, see Using automated resource generation based on natural language processing (NLP) of the FHIR DocumentReference resource type in AWS HealthLake.

Example Updating a Patient resource type using a PUT request

When you make a PUT request, you will need the data store's endpoint, the name of the resource type you want to update, an identifier, and a JSON request body.

If you use PUT to create a new resource, it uses the identifier provided to create the new resource.

PUT Request

Example structure of a valid PUT request:

PUT https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Patient/2de04858-ba65-44c1-8af1-f2fe69a977d9
JSON Request Body

An example JSON body used to update the specified patient resource.

{ "id": "2de04858-ba65-44c1-8af1-f2fe69a977d9", "resourceType": "Patient", "active": true, "name": [ { "use": "official", "family": "Doe", "given": [ "Jane" ] }, { "use": "usual", "given": [ "Jane" ] } ], "gender": "female", "birthDate": "1985-12-31" }
JSON response

You will receive the following JSON in response to confirm the change:

{ "id": "2de04858-ba65-44c1-8af1-f2fe69a977d9", "resourceType": "Patient", "active": true, "name": [{ "use": "official", "family": "Doe", "given": [ "Jane" ] }, { "use": "usual", "given": [ "Jane" ] } ], "gender": "female", "birthDate": "1985-12-31", "meta": { "lastUpdated": "2020-11-23T06:43:45.133Z" } }

Conditional Update

Conditional Update allows updating an existing resource based on some identification search criteria, rather than by logical id. When the server processes this update, it performs a search using its standard search capabilities for the resource type, with the goal of resolving a single logical id for this request.

The action it takes depends on how many matches are found:

  • No matches, no id provided in the request body: The server creates the resource.

  • No matches, id provided and resource doesn't already exist with the id: The server treats the interaction as an Update as Create interaction.

  • No matches, id provided and already exist: The server rejects the update with a 409 Conflict error.

  • One Match, no resource id provided OR (resource id provided and it matches the found resource): The server performs the update against the matching resource as above where, if the resource was updated, the server SHALL return a 200 OK;

  • One Match, resource id provided but does not match resource found: The server returns a 409 Conflict error indicating the client id specification was a problem preferably with an OperationOutcome

  • Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough preferably with an OperationOutcome

Example – Update a patient resource whose name is peter, birthdate is 1st Jan 2000 and phone number 1234567890:
PUT https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Patient?name=peter&birthdate=2000-01-01&phone=1234567890