---
updatedAt: 2026-05-29T17:03:39.000Z
---

# Invite users to a room

Allows an authenticated user of a room to invite members and/or guests.

You can invite users by specifying either their email address or their username.
In both cases the user is notified by email. However, when inviting by username,
the user is immediately added to the room.

**Authorization scope**: `rooms:write`


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "MURAL Public API",
    "description": "MURAL's Public API\n",
    "termsOfService": "https://start.mural.co/developer-beta/terms",
    "contact": {
      "name": "MURAL",
      "email": "m4d@mural.co"
    },
    "version": "1.0.0",
    "x-logo": {
      "url": "https://app.mural.co/static/images/new-logo.svg",
      "href": "https://mural.co"
    }
  },
  "servers": [
    {
      "url": "https://app.mural.co/api/public/{version}",
      "description": "MURAL Public API",
      "variables": {
        "version": {
          "default": "v1",
          "enum": [
            "v1"
          ]
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Users"
    }
  ],
  "paths": {
    "/rooms/{roomId}/users/invite": {
      "post": {
        "security": [
          {
            "oauth2": [
              "rooms:write"
            ]
          }
        ],
        "tags": [
          "Users"
        ],
        "summary": "Invite users to a room",
        "description": "Allows an authenticated user of a room to invite members and/or guests.\n\nYou can invite users by specifying either their email address or their username.\nIn both cases the user is notified by email. However, when inviting by username,\nthe user is immediately added to the room.\n\n**Authorization scope**: `rooms:write`\n",
        "operationId": "inviteUsersToRoom",
        "parameters": [
          {
            "$ref": "#/components/parameters/roomId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteUsersToRoom"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "description": "Array of invitations",
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RoomInvitationResult"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BodyBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Room not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoomNotFound"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.mural.co/api/public/v1/authorization/oauth2",
            "tokenUrl": "https://app.mural.co/api/public/v1/authorization/oauth2/token",
            "refreshUrl": "https://app.mural.co/api/public/v1/authorization/oauth2/token",
            "scopes": {
              "rooms:read": "Read information about rooms (for room members and owners).",
              "rooms:write": "Write information about rooms (for room owners).",
              "users:read": "Read information about users (guests, members, and visitors).",
              "workspaces:write": "Write information about workspaces (for workspace owners)",
              "workspaces:read": "Read information about workspaces (for workspace members and owners).",
              "murals:read": "Read information about murals (for mural members and owners).",
              "murals:write": "Write information about murals (for mural members and owners).",
              "meeting-consents:read": "Read who was asked for consent to record a meeting, and how each of them answered (for attendees of that meeting).",
              "meeting-consents:write": "Register meetings for recording, ask their attendees for consent, and answer on the authenticated user's own behalf.",
              "identity:read": "Read information about currently authenticated user.",
              "templates:read": "Read information about templates.",
              "templates:write": "Write information about templates (for templates owners)"
            }
          }
        }
      }
    },
    "schemas": {
      "BaseError": {
        "description": "Thorough details regarding an error response from the API.",
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "description": "Error code",
            "example": "ERROR",
            "type": "string",
            "maxLength": 36
          },
          "message": {
            "description": "Short, human readable, description of the error.",
            "example": "Unknown server error",
            "type": "string"
          }
        }
      },
      "DetailedError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseError"
          },
          {
            "type": "object",
            "properties": {
              "details": {
                "description": "Error details.",
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "code",
                    "message"
                  ],
                  "properties": {
                    "code": {
                      "description": "Error code",
                      "example": "SUB_ERROR",
                      "type": "string",
                      "maxLength": 36
                    },
                    "message": {
                      "description": "Short, human readable, description of the error.",
                      "example": "Unknown server error",
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "BodyBadRequest": {
        "description": "The request body was malformed or had invalid parameters.",
        "allOf": [
          {
            "$ref": "#/components/schemas/DetailedError"
          },
          {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Request body has invalid parameters.",
                "example": "BODY",
                "enum": [
                  "BODY"
                ]
              }
            }
          }
        ]
      },
      "RoomNotFound": {
        "description": "The requested room was not found.",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseError"
          },
          {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "ROOM_NOT_FOUND",
                "enum": [
                  "ROOM_NOT_FOUND"
                ]
              },
              "message": {
                "example": "The room was not found or does not exist."
              }
            }
          }
        ]
      },
      "RoomInvitation": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "The email address of the invited user.",
            "example": "example@example.com"
          },
          "username": {
            "type": "string",
            "description": "The username of the invited user.",
            "example": "ua9642bb1052c3465b5464271"
          }
        }
      },
      "InviteUsersToRoom": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The custom message to be sent in the email invitation.",
            "example": "Invitation to Management room"
          },
          "invitations": {
            "description": "Array of invitations",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RoomInvitation"
            }
          },
          "sendEmail": {
            "type": "boolean",
            "description": "Indicates if the invitation will or will not be emailed. Default value is true.",
            "default": true,
            "example": true
          }
        },
        "required": [
          "invitations"
        ]
      },
      "RoomInvitationResult": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "User's email.",
            "example": "user@mural.co"
          },
          "refCode": {
            "type": "string",
            "description": "The room's invitation code.",
            "example": "2fd2fb3d-7286-40b6-813a-88e3f3cd061b"
          },
          "rejected": {
            "type": "boolean",
            "description": "When true, the invitation process was rejected.",
            "example": true
          },
          "reason": {
            "type": "string",
            "description": "Reason for the rejection.",
            "example": "INVITE_AS_GUEST_DISABLED"
          },
          "username": {
            "type": "string",
            "description": "Returned when the user is added as member or guest.",
            "example": "ua2deo48ccd34579e3bfc0074"
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "No authorization",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/BaseError"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "enum": [
                        "UNAUTHORIZED",
                        "TOKEN_EXPIRED"
                      ]
                    }
                  }
                }
              ]
            },
            "examples": {
              "authorization": {
                "summary": "No authorization",
                "value": {
                  "code": "UNAUTHORIZED",
                  "message": "You don't have the required permissions to access this endpoint."
                }
              },
              "expiredToken": {
                "summary": "Expired token",
                "value": {
                  "code": "TOKEN_EXPIRED",
                  "message": "Your token has expired. You need to refresh your OAuth token."
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Access denied",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/BaseError"
            },
            "examples": {
              "invalidScope": {
                "$ref": "#/components/examples/invalidScope"
              }
            }
          }
        }
      },
      "ServerError": {
        "description": "API error",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/DetailedError"
                },
                {
                  "type": "object",
                  "properties": {
                    "code": {
                      "enum": [
                        "INTERNAL_SERVER_ERROR"
                      ],
                      "example": "INTERNAL_SERVER_ERROR"
                    },
                    "message": {
                      "example": "An unexpected condition was encountered that prevented us from fulfilling the request. Try it again later, please."
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "BodyBadRequest": {
        "description": "Request invalid or malformed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/BodyBadRequest"
            }
          }
        }
      }
    },
    "examples": {
      "invalidScope": {
        "summary": "Invalid scope",
        "value": {
          "code": "INVALID_SCOPE",
          "message": "Logged in user does not have the right scope(s) to access this resource."
        }
      }
    },
    "parameters": {
      "roomId": {
        "in": "path",
        "name": "roomId",
        "schema": {
          "type": "number"
        },
        "required": true,
        "description": "Unique identifier of a room.\n",
        "example": 1610033618903
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false
  }
}
```