> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/invite-external-guest-users.md).

# Invite External Guest Users

Invite an external person as a guest user

### Description

Sends a Microsoft Entra ID guest invitation to an external email address. Optionally the guest is added to a group, and profile details such as name, company, usage location, manager and sponsor are set on the guest account right away. The invitation email and the landing page can be customized. Without the email, the job output shows the link the guest uses to accept the invitation.

### Common use cases

* Basic guest invite: provide only the email address and the display name; all profile and group parameters can be left blank.
* Full onboarding: supply all optional fields to set profile properties, assign a manager and a sponsor, and add the guest to a group in a single run.

### Parameter interactions

* Profile properties (`givenName`, `surname`, `companyName`, `usageLocation`) are applied only when they are not empty; omitting them skips the update call entirely.
* Manager assignment, sponsor assignment and group membership each require their respective parameters; all of them are skipped silently when not provided.
* The usage location must be a two-letter ISO 3166-1 country code, for example `GB` for the United Kingdom (not `UK`) and `GR` for Greece (not `EL`). An unknown code stops the run before the invitation is sent, so no guest account and no invitation email are created.

### Invitation without email

When "Send the invitation email?" is turned off, Entra ID creates the guest account without sending an email, the same as clearing "Send invite message" in the Entra admin center. The guest stays in the state "pending acceptance" until the first sign-in.

* The job output shows the redemption link once, in the section "Invite Guest User". Pass it to the guest through another channel, for example your own email or a chat message.
* Instead of the redemption link, the guest can sign in through a link that contains your tenant, for example `https://myapps.microsoft.com/?tenantid=<tenant id>`. The consent prompt appears at the first sign-in.
* Guests who sign in with an alias of the invited address need the redemption link.
* The redirect URL from "Customize the invitation?" still applies: after accepting through the redemption link, the guest lands there.
* The invitation message is part of the email only and is not used without it.

### Location

Organization → General → Invite External Guest Users

**Full Runbook name**

rjgit-org\_general\_Invite-external-guest-users

### Details

| Property         | Value                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------- |
| Version          | 2.1.0                                                                                    |
| Required modules | <p>RealmJoin.RunbookHelper (>= 0.8.10)<br>Microsoft.Graph.Authentication (>= 2.41.2)</p> |
| Schedulable      | no                                                                                       |

### Permissions

#### Application permissions

* **Type**: Microsoft Graph
  * Group.ReadWrite.All
    * *Verifies the target group and adds the guest via /groups/{id}/members/$ref*
  * Organization.Read.All
    * *Reads the tenant id to build the default invite redirect URL*
  * User.ReadWrite.All
    * *Creates the invitation, patches guest profile properties and sets manager and sponsor*

### Parameters

#### InvitedUserEmail

Email address of the person to invite.

| Property      | Value  |
| ------------- | ------ |
| Required      | true   |
| Default Value |        |
| Type          | String |

#### InvitedUserDisplayName

Name shown for the guest in the directory.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### GroupId

Group the guest is added to. Preset in the runbook customization; empty means none.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### GivenName

First name of the guest.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### Surname

Last name of the guest.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### CompanyName

Company the guest works for.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### ManagerName

User who becomes the guest's manager.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### SponsorName

User recorded as the guest's sponsor.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### SendInvitationMessage

Emails the invitation to the guest. Without the email, the job output shows the link the guest uses to accept the invitation, to pass on by other means.

| Property      | Value   |
| ------------- | ------- |
| Required      | false   |
| Default Value | True    |
| Type          | Boolean |

#### CustomizeInvitation

Shows fields for an own invitation message and redirect URL.

| Property      | Value   |
| ------------- | ------- |
| Required      | false   |
| Default Value | False   |
| Type          | Boolean |

#### InvitationMessage

Text included in the invitation email. Not used when no invitation email is sent.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### InviteRedirectUrl

Page the guest lands on after accepting, for example a SharePoint site.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

#### UsageLocation

Two-letter ISO country code, for example US, DE or GB for the United Kingdom, needed before licenses can be assigned. An unknown code such as UK stops the run before the invitation is sent.

| Property      | Value  |
| ------------- | ------ |
| Required      | false  |
| Default Value |        |
| Type          | String |

[Back to Runbook Reference overview](https://docs.realmjoin.com/automation/runbooks/runbook-references.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/automation/runbooks/runbook-references/org/general/invite-external-guest-users.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
