Skip to main content

Invite User Endpoint

POST /admin/projects/:projectId/invite​

Invite a new user to the project. This will perform the following actions:

  1. Search for an existing user with the provided email, if given
  2. Search for an existing profile resource (Patient, Practitioner, or RelatedPerson)
  3. Create a new User, if no existing User was found,
    1. Set the password if password is given
    2. Generate a password reset url
  4. Create a new profile resource, if no existing profile was found
  5. Create a corresponding ProjectMembership resource, for the (user, profile) pair
  6. Send an invite email, if sendEmail is true

Parameters​

{
  resourceType: 'Patient' | 'Practitioner' | 'RelatedPerson';
  firstName: string;
  lastName: string;
  email?: string;
  externalId?: string;
  scope?: 'project' | 'server';
  password?: string;
  sendEmail?: boolean;
  membership?: Partial<ProjectMembership>;
  upsert?: boolean;
  forceNewMembership?: boolean;
  mfaRequired?: boolean;
}
parameterdescription
resourceTypeThe User's profile resourceType
firstName, lastNameThe first and last names that will be assigned to user's profile resource. Ignored if a profile resource already exists
emailThe email address assigned to the User. Used to identify users within each project
externalIdThe unique id provided by external identity provider (if applicable). See Using External Ids
passwordThe User's password
scopeThe scope of the user. If project, the user will be scoped to the project. If server, the user will be a server scoped user. Defaults to server for Practitioners and project for Patients. See server vs project scoped user guide
sendEmailIf true, send an invite email to the user. If self-hosting, see our guide on setting up SES
membershipUsed to override any fields of the resulting ProjectMembership resource. Common use cases include:
  • Setting Access Policies upon invite
  • Overriding the default ProjectMembership.profile
upsertIf true, allows updating existing users and profiles instead of creating new ones. When enabled, the invite will search for existing users and profiles and update them if found, rather than throwing an error message.
forceNewMembershipIf true, forces creation of a new ProjectMembership resource even if one already exists for the user/profile combination in the project.
mfaRequiredIf true, requires the user to set up Multi-Factor Authentication (MFA) during their first login. A MFA secret will be automatically generated for the user. See MFA documentation for more details.

Constraints​

  • Either email or externalId is required.

Examples​

Inviting a Practitioner​

await medplum.post('admin/projects/:projectId/invite', {
  resourceType: 'Practitioner',
  firstName: 'George',
  lastName: 'Washington',
  email: 'dr.gw@example.gov',
  password: 'lib3rty0rDe4th!',
});

Example Response:

Returns the ProjectMembership associated with the new user

{
  resourceType: 'ProjectMembership',
  id: ':id',
  admin: true,
  project: {
    reference: 'Project/:projectId',
  },
  user: {
    reference: 'User/:userId',
    display: 'dr.gw@example.gov'
  },
  profile: {
    reference: 'Practitioner/:practitionerId',
    display: 'George Washington'
  },
}

Inviting a Patient​

await medplum.post('admin/projects/:projectId/invite', {
  resourceType: 'Patient',
  firstName: 'George',
  lastName: 'Washington',
  email: 'patient.gw@example.gov',
  password: 'lib3rty0rDe4th!',
});

Example Response:

Returns the ProjectMembership associated with the new user

{
  resourceType: 'ProjectMembership',
  id: ':id',
  admin: true,
  project: {
    reference: 'Project/:projectId'
  },
  user: {
    reference: 'User/:userId',
    display: 'patient.gw@example.gov'
  },
  profile: {
    reference: 'Patient/:patientId',
    display: 'George Washington'
  }
}

Inviting a User with MFA Required​

await medplum.post('admin/projects/:projectId/invite', {
  resourceType: 'Practitioner',
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane.doe@example.com',
  mfaRequired: true,
});

When mfaRequired: true is set, the user will be required to enroll in Multi-Factor Authentication during their first login. See MFA documentation for more details.

See Also​