User $update-email | Medplum

On this page

This operation updates both the User resource (for authentication) and optionally the associated profile resource (Patient, Practitioner, or RelatedPerson) with the new email address.

Use Cases

• Patient Email Changes: Update a patient's email address for both login credentials and contact information
• Provider Contact Updates: Keep practitioner email addresses synchronized between authentication and profile records
• Credential Recovery Scenarios: Update email addresses during account recovery workflows
• User Migration: Change email addresses as part of user account migration or consolidation

POST [base]/User/[id]/$update-email

Privileged Operation

This operation requires Project Admin privileges

User vs Profile Email

In Medplum, the User.email field controls authentication and login, while the profile resource's telecom field displays contact information. If you update only the profile resource email, users will not be able to log in with the new email address. Use this operation to update both atomically.

Parameters

The input is a FHIR Parameters resource containing:

Output

The operation returns the updated User resource with:

• email set to the new email address
• emailVerified set to false (unless verification was skipped)

If updateProfileTelecom is true:

• Adds the new email to the profile's telecom array with use: 'work'
• Marks the old email in telecom with use: 'old'

Examples

Request:

TypeScript:

await medplum.post(`fhir/R4/User/${userId}/$update-email`, {

resourceType: 'Parameters',

parameter: [

{ name: 'email', valueString: 'newemail@example.com' },

{ name: 'updateProfileTelecom', valueBoolean: true }

]

});

curl -X POST 'https://api.medplum.com/fhir/R4/User/example-user-id/$update-email' \
  
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  
  -H "Content-Type: application/fhir+json" \
  
  -d '{

"resourceType": "Parameters",

"parameter": [

{ "name": "email", "valueString": "newemail@example.com" },

{ "name": "updateProfileTelecom", "valueBoolean": true }

]

}'

Response (200 OK):

{
  "resourceType": "User",
  "id": "example-user-id",
  "email": "newemail@example.com",
  "emailVerified": false,
  "firstName": "Alice",
  "lastName": "Smith",
  "project": {
    "reference": "Project/example-project-id"
  }
}

Finding User ID from ProjectMembership

To update a patient's email when you only have their Patient ID:

// Find the user via ProjectMembership

const memberships = await medplum.searchResources('ProjectMembership', {

profile: profileReference

});

const userId = memberships[0].user?.reference?.split('/')[1];

// Update the email

await medplum.post(`fhir/R4/User/${userId}/$update-email`, {

resourceType: 'Parameters',

parameter: [

{ name: 'email', valueString: 'newemail@example.com' },

{ name: 'updateProfileTelecom', valueBoolean: true }

]

});

Error Responses