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`](/content/docs/api/fhir/resources/patient/index.html), [`Practitioner`](/content/docs/api/fhir/resources/practitioner/index.html), or [`RelatedPerson`](/content/docs/api/fhir/resources/relatedperson/index.html))
3. Create a new [`User`](/content/docs/api/fhir/medplum/user/index.html), if no existing [`User`](/content/docs/api/fhir/medplum/user/index.html) 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`](/content/docs/api/fhir/medplum/projectmembership/index.html) 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)

```ts
{
  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](/content/docs/api/fhir/medplum/user/index.html) [profile resourceType](/content/docs/user-management#profiles/index.html) |
| `firstName`, `lastName` | The first and last names that will be assigned to user's [profile resource](/content/docs/user-management#profiles/index.html). Ignored if a profile resource already exists |
| `email`         | The email address assigned to the [User](/content/docs/api/fhir/medplum/user/index.html). Used to identify users within each project |
| `externalId`   | The unique id provided by external identity provider (if applicable). See [Using External Ids](/content/docs/auth/external-identity-providers/index.html) |
| `password`      | The [User's](/content/docs/api/fhir/medplum/user/index.html) 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](/content/docs/user-management/project-vs-server-scoped-users/index.html) |
| `sendEmail`     | If `true`, send an invite email to the user. If self-hosting, see our [guide on setting up SES](/content/docs/self-hosting/install-on-aws#setup-ses/index.html) |
| `membership`    | Used to override any fields of the resulting [`ProjectMembership`](/content/docs/api/fhir/medplum/projectmembership/index.html) resource. Common use cases include: <br>- Setting [Access Policies](/content/docs/access/access-policies/index.html) upon invite <br>- 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`](/content/docs/api/fhir/medplum/projectmembership/index.html) 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](/content/docs/auth/mfa/index.html) for more details. |

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

- Either `email` or `externalId` is required.

### 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)

- Typescript
- CLI
- cURL

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

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

```bash
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`](/content/docs/api/fhir/medplum/projectmembership/index.html) associated with the new user

```ts
{
  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)

- Typescript
- CLI
- cURL

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

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

```bash
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`](/content/docs/api/fhir/medplum/projectmembership/index.html) associated with the new user

```ts
{
  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)

- Typescript
- CLI
- cURL

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

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

```bash
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](/content/docs/auth/mfa/index.html) for more details.