Invite User Endpoint | Medplum

On this page

POST /admin/projects/:projectId/invite [​](/content/docs/api/project-admin/invite#post-adminprojectsprojectidinvite "Direct link to post-adminprojectsprojectidinvite"/index.html)

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 [​](/content/docs/api/project-admin/invite#parameters "Direct link to Parameters"/index.html)

{
  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;
}
parameter description
resourceType The User's profile resourceType
firstName, lastName The first and last names that will be assigned to user's profile resource. Ignored if a profile resource already exists
email The email address assigned to the User. Used to identify users within each project
externalId The unique id provided by external identity provider (if applicable). See Using External Ids
password The User's password
scope The 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
sendEmail If true, send an invite email to the user. If self-hosting, see our guide on setting up SES
membership Used to override any fields of the resulting ProjectMembership resource. Common use cases include:
- Setting Access Policies upon invite
- Overriding the default ProjectMembership.profile
upsert If 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.
forceNewMembership If true, forces creation of a new ProjectMembership resource even if one already exists for the user/profile combination in the project.
mfaRequired If 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 [​](/content/docs/api/project-admin/invite#constraints "Direct link to Constraints"/index.html)

Examples [​](/content/docs/api/project-admin/invite#examples "Direct link to Examples"/index.html)

Inviting a Practitioner [​](/content/docs/api/project-admin/invite#inviting-a-practitioner "Direct link to Inviting a Practitioner"/index.html)

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

medplum post admin/projects/:projectId/invite \
'{
  "resourceType": "Practitioner",
  "firstName": "George",
  "lastName": "Washington",
  "email": "dr.gw@example.gov",
  "membership": {
    "admin": true
  }
}'

curl https://api.medplum.com/admin/projects/:projectId/invite \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceType": "Practitioner",
  "firstName": "George",
  "lastName": "Washington",
  "email": "dr.gw@example.gov",
  "membership": {
    "admin": true
  }
}'

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 [​](/content/docs/api/project-admin/invite#inviting-a-patient "Direct link to Inviting a Patient"/index.html)

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

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

curl https://api.medplum.com/admin/projects/:projectId/invite \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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 [​](/content/docs/api/project-admin/invite#inviting-a-user-with-mfa-required "Direct link to Inviting a User with MFA Required"/index.html)

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

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

curl https://api.medplum.com/admin/projects/:projectId/invite \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "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.