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

# Register a guest

`POST /v1/guests/register`

## Request

- Base URL: `https://envelope.so/api`
- URL: `https://envelope.so/api/v1/guests/register`
- Auth: API key in header `x-api-key`

Registers a new guest or confirms an existing guest through a public form submission.

## Request body

- object
  - `eventId` string, required: ID of the event
  - `formData` object, required
    - `properties` object, required
      - `firstName` string: First name of the guest
      - `lastName` string: Last name of the guest
      - `email` string, required: Email address of the guest
    - `partners` integer: Number of additional guests (+1, +2)
    - `givenConsents` string[]: Array of consent IDs that the guest has given
  - `guestId` string: ID of existing guest if updating
  - `pageId` string: ID of the page containing the form

## Response `200`

Guest registered successfully.

- Guest
  - `_id` string, required: Guest ID
  - `event` string, required: Event ID
  - `confirmedAt` string, date-time, nullable: Date and time when the guest was confirmed
  - `attendedAt` string, date-time, nullable: Date and time when the guest attended the event
  - `starred` boolean: Indicates if the guest is starred
  - `status` object, required: Guest status information including confirmation, attendance, consents and check-in details
    - `confirmation` integer, required: -1 = declined, 0 = default, 1 = confirmed, 2 = confirmed + 1 partner, 3 = confirmed + 2 partners
    - `attendance` integer, required: 0 = default, 1 = attended, 2 = attended + 1 partner, 3 = attended + 2 partners
    - `declineMessage` string, nullable: Message from the guest when they declined the invitation
    - `givenConsents` string[], required: Array of consents that the guest has given
    - `visitedZones` string[], required: Array of zone IDs that the guest has visited
    - `addMethod` 'batchImport' | 'singleAdd' | 'checkInAdd' | 'publicRegistration': Method used to add the guest to the event
    - `checkInMethod` 'qrScan' | 'manual', nullable: Method used to check in the guest
  - `properties` object, required: Guest properties including default required fields and any custom properties defined for the event
    - `firstName` string, required: First name of the guest
    - `lastName` string, required: Last name of the guest
    - `email` string, required: Email address of the guest
    - `lang` string, required: Language of the guest

## Other responses

- `400`: Invalid request parameters or registration constraints not met.
- `403`: Event is full or registration not allowed.
- `404`: Event, guest, or form section not found.

---

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