---
title: "Create a new guest"
method: POST
path: "/v1/guests/"
tags: ["Guests"]
---

# Create a new guest

`POST /v1/guests/`

## Request

- Base URL: `https://api.educaplay.com`
- URL: `https://api.educaplay.com/v1/guests/`
- Auth: HTTP bearer

Creates guest invitations owned by the authenticated user. Without `names`, creates one guest: if `name` is omitted or empty, an auto-generated placeholder name is used. With `names[]`, creates one guest per name (up to 500 per request) and responds with the list. `groups[]` tags the new guests with existing groups. Each guest carries its nine-letter access code, its direct access link and the content of its QR code.

## Response `200`

Guest created. With `names[]`, a list of the guests created.

- union
  - GuestSummary
    - `id` integer, required
    - `name` string, required
    - `code` string, required: Auto-generated nine-letter access code in the form `XXX-XXX-XXX`. Share it with the guest to let them play the mentor's activities.
    - `_links` HalLink[], required
      - `rel` string, required
      - `href` string, uri, required
    - `link` string, uri, required: Direct access link. Opening it shows a confirmation screen ("Enter as …") and signs the guest in without typing the code. It is the same secret as the code: share it with the same care.
    - `qr` string, uri, required: Content to encode in the guest's QR code. Educaplay does not render QR images server-side: it encodes this URL on the client with the same generator used for game QR codes, and so can you.
    - `groups` GuestGroup[], required: Groups (tags) the guest belongs to. A guest may be in several groups or in none.
      - `id` integer, required
      - `name` string, required
      - `count` integer: Number of guests tagged with this group. Only present when listing groups.
  - GuestListResponse
    - `_embedded` object, required
      - `guests` GuestSummary[], required
        - `id` integer, required
        - `name` string, required
        - `code` string, required: Auto-generated nine-letter access code in the form `XXX-XXX-XXX`. Share it with the guest to let them play the mentor's activities.
        - `_links` HalLink[], required
          - `rel` string, required
          - `href` string, uri, required
        - `link` string, uri, required: Direct access link. Opening it shows a confirmation screen ("Enter as …") and signs the guest in without typing the code. It is the same secret as the code: share it with the same care.
        - `qr` string, uri, required: Content to encode in the guest's QR code. Educaplay does not render QR images server-side: it encodes this URL on the client with the same generator used for game QR codes, and so can you.
        - `groups` GuestGroup[], required: Groups (tags) the guest belongs to. A guest may be in several groups or in none.
          - `id` integer, required
          - `name` string, required
          - `count` integer: Number of guests tagged with this group. Only present when listing groups.
    - `_links` HalLink[], required
      - `rel` string, required
      - `href` string, uri, required

## Other responses

- `401`: Authentication is missing or the Bearer token is invalid.
- `402`: The free plan limit for guest invitations has been reached. Upgrade to an Academic or Commercial subscription to create more guests.
- `429`: The request rate limit for the account has been exceeded. Limits depend on the subscription plan (Basic 120, Advanced 300, Academic 600 and Commercial 1200 requests per minute) and are measured over a fixed 60 second window. Wait the number of seconds given in the `Retry-After` header before retrying.

## Changes

- **2026-10-19** `e31d97013d0d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/educaplay/apis/educaplay-api/changes/v1/guests/post.md)

---

[API](https://skmtc.dev/educaplay/apis/educaplay-api.md) · [All operations](https://skmtc.dev/educaplay/apis/educaplay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/educaplay/apis/educaplay-api/revisions/e31d97013d0d?raw)