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;
  password?: string;
  sendEmail?: boolean;
  membership?: Partial<ProjectMembership>;
}
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
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

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'
  }
}

See Also​