---
title: "List all guests"
method: GET
path: "/v1/guests"
tags: ["Guests"]
---

# List all guests

`GET /v1/guests`

## Request

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

Retrieves a paginated list of guests with filtering, sorting, and search capabilities.

## Query parameters

- `event` string, required
- `skip` integer
- `limit` integer
- `search` string
- `email` string
- `sortBy` string
- `filterBy` string

## Response `200`

List of guests with pagination metadata.

- object
  - `results` GuestWithPopulated[]
    - `_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
    - `_populated` object, required
      - `properties` object, required: Localized and human-readable guest properties
      - `status` object, required: Localized and human-readable guest status
        - `confirmation` string, required: Localized confirmation status
        - `attendance` string, required: Localized attendance status
  - `total` integer: Total count of matching guests

## Other responses

- `401`: Invalid or missing API key.

---

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