# Luma Documentation

> Use the Luma API to view and update your events, communities, and audience members. Create and manage events, register guests, and so much more.

## API Reference
- [Getting Started](https://docs.luma.com/reference/getting-started-with-your-api.md): Make your first request in just a few minutes.
- [Rate Limits](https://docs.luma.com/reference/rate-limits.md)
- [API Formats](https://docs.luma.com/reference/formats.md): Notes on various formats and quirks.
- [Code Examples](https://docs.luma.com/reference/examples.md): We'll add different examples / tutorials to this page showing how people are using the Luma API.
- [API Conventions](https://docs.luma.com/reference/api-conventions.md)
- [Changelog](https://docs.luma.com/reference/changelog.md)
- [Create Event](https://docs.luma.com/reference/post_v1-events-create.md)
- [Update Event](https://docs.luma.com/reference/post_v1-events-update.md)
- [Get Event](https://docs.luma.com/reference/get_v1-events-get.md): Return full details about an event you have manage access for, including hosts and a breakdown of guest counts by status.
- [Request Event Cancellation](https://docs.luma.com/reference/post_v1-events-cancel-request.md): Request a cancellation token for an event. Canceling an event is irreversible — it notifies all guests, processes refunds, and permanently deletes the event. Because of this, cancellation uses a two-step flow: first request a token here, then pass it to /events/cancel to execute. The token expires after 15 minutes.
- [Cancel Event](https://docs.luma.com/reference/post_v1-events-cancel.md): Cancel an event. You must first call /events/cancel/request to get a cancellation_token, then pass it here. This is irreversible — the event will be deleted, all guests will be notified, and refunds will be processed if should_refund is true. For paid events, you must specify should_refund.
- [Add Guests](https://docs.luma.com/reference/post_v1-events-guests-add.md): Add guests to the event. By default, guests are added with the status "Going" (approved) and receive one ticket of the default ticket type. Use the `ticket` or `tickets` parameter to specify custom ticket assignments. Get available ticket types using `/v1/events/ticket-types/list`. Use `approval_status` to add guests as pending approval or on the waitlist instead of immediately approved. Use `registration_answers` on each guest to record answers to the event's registration questions — question IDs come from the `registration_questions` field of Get Event.
- [Get Guest](https://docs.luma.com/reference/get_v1-events-guests-get.md): Get detailed information for an event guest by looking them up by their ID. This supports looking them up by different parameters.  This response includes `event_ticket_orders`, which includes `coupon_info` when a coupon was applied.
- [List Guests](https://docs.luma.com/reference/get_v1-events-guests-list.md): Get list of guests who have registered or been invited to an event.  This list response includes guest summaries and `event_tickets`, but not order-level details like `event_ticket_orders`. Use `/v1/events/guests/get` when you need detailed ticket order data for a specific guest.
- [Update Guest Status](https://docs.luma.com/reference/post_v1-events-guests-update-status.md): Update a guest’s status. Set `status` to `approved` ("Going"), `declined`, `pending_approval`, or `waitlist`. Use `should_refund` to refund a paid guest when moving them out of an approved state. Use `message` to include a personal note in the email we send the guest. To send a soft invite that guests can accept, use `/v1/events/guests/send-invites` instead.
- [Update Guest Tickets](https://docs.luma.com/reference/post_v1-events-guests-update-tickets.md): Add or remove tickets from an existing guest. This is an administrative operation: added tickets are complimentary, removed tickets are invalidated, and no payment or refund is processed. You can’t change tickets for guests with pending payment holds. Administrative ticket changes can exceed event or ticket-type capacity.
- [Send Invites](https://docs.luma.com/reference/post_v1-events-guests-send-invites.md): Send guests an invite to an event. We'll send an email, and if their phone number is linked to their Luma account, they'll also receive an SMS.
- [Add Host](https://docs.luma.com/reference/post_v1-events-hosts-add.md): Add a host to an event. This works for both managers and check-in staff — use the access_level parameter to control permissions.
- [Update Host](https://docs.luma.com/reference/post_v1-events-hosts-update.md): Update a host's permissions or visibility on an event. Use this to change a host between check-in and manager access levels. The event creator's access level cannot be changed.
- [Remove Host](https://docs.luma.com/reference/post_v1-events-hosts-remove.md): Remove a host from an event. The event creator cannot be removed.
- [Create Ticket Type](https://docs.luma.com/reference/post_v1-events-ticket-types-create.md): Create a new ticket type for an event
- [Update Ticket Type](https://docs.luma.com/reference/post_v1-events-ticket-types-update.md): Update an existing ticket type configuration
- [Get Ticket Type](https://docs.luma.com/reference/get_v1-events-ticket-types-get.md): Get a single ticket type by ID
- [List Ticket Types](https://docs.luma.com/reference/get_v1-events-ticket-types-list.md): List all ticket types for an event
- [Delete Ticket Type](https://docs.luma.com/reference/post_v1-events-ticket-types-delete.md): Soft delete a ticket type. Cannot delete if tickets have been sold or if it's the last visible ticket type.
- [Create Coupon](https://docs.luma.com/reference/post_v1-events-coupons-create.md): Create a coupon that can be applied when a guest is registering for an event. Restrict it to a ticket type with `event_ticket_type_id` — when that ticket type is hidden, this creates an unlock (access) code. You are not able to edit the coupon terms after it has been created.
- [Update Coupon](https://docs.luma.com/reference/post_v1-events-coupons-update.md)
- [List Event Coupons](https://docs.luma.com/reference/get_v1-events-coupons-list.md): List all coupons that have been created for an event.
- [Get Calendar](https://docs.luma.com/reference/get_v1-calendars-get.md): Get information about the calendar.
- [Update Calendar](https://docs.luma.com/reference/post_v1-calendars-update.md): Update a calendar's settings. Only the provided fields are changed.
- [List Events](https://docs.luma.com/reference/get_v1-calendars-events-list.md): Every event and API key on Luma is managed by a [Luma Calendar](https://help.luma.com/p/luma-calendar-overview). By default this lists the events your Calendar manages.  Each event includes an `access` field. Pass `access=manage&access=view` to also return events that are listed on the Calendar but managed elsewhere — those come back with `access: "view"`, their location obfuscated to city level, and host-only fields like `meeting_url`, `registration_questions`, and `feedback_email` omitted. Private events the Calendar doesn't manage are never returned.
- [Lookup Event](https://docs.luma.com/reference/get_v1-calendars-events-lookup.md): See if an event already exists on the calendar. This is useful when figuring out if you want to submit an event to the calendar.
- [Add Event](https://docs.luma.com/reference/post_v1-calendars-events-add.md): Add or submit an existing event (on Luma or on an external platform) to the Luma calendar. By default, events added by a calendar manager are approved immediately. Use `submission_mode: "pending"` to keep the submission pending.  On calendars with `require-manage-access`, submitting a Luma event you manage can also grant the target calendar manage access once the submission is approved.
- [Approve Event](https://docs.luma.com/reference/post_v1-calendars-events-approve.md): Approve a pending event submission on your calendar. The event becomes visible on the calendar and the submitter is notified.
- [Reject Event](https://docs.luma.com/reference/post_v1-calendars-events-reject.md): Reject a pending event submission on your calendar. If the event is still pending, the submitter is notified.
- [List Calendar Admins](https://docs.luma.com/reference/get_v1-calendars-admins-list.md): List all admins for the calendar.
- [Import Contacts](https://docs.luma.com/reference/post_v1-calendars-contacts-import.md): Import contacts to your calendar to easily invite them to events and send them newsletters.
- [List Contacts](https://docs.luma.com/reference/get_v1-calendars-contacts-list.md)
- [Block Contact](https://docs.luma.com/reference/post_v1-calendars-contacts-block.md): Block a contact so they can’t follow your calendar or join its events. They stop receiving your invites and newsletters until you restore them.
- [Remove Contact](https://docs.luma.com/reference/post_v1-calendars-contacts-remove.md): Remove a contact from your calendar. They stop receiving your invites and newsletters but can follow again on their own later.
- [Restore Contact](https://docs.luma.com/reference/post_v1-calendars-contacts-restore.md): Restore a blocked or removed contact, returning them to your active contacts.
- [Create Contact Tag](https://docs.luma.com/reference/post_v1-calendars-contact-tags-create.md)
- [Update Contact Tag](https://docs.luma.com/reference/post_v1-calendars-contact-tags-update.md)
- [Delete Contact Tag](https://docs.luma.com/reference/post_v1-calendars-contact-tags-delete.md)
- [Apply Contact Tag](https://docs.luma.com/reference/post_v1-calendars-contact-tags-apply.md): Apply a tag to existing calendar contacts. This will not create new contacts.
- [Unapply Contact Tag](https://docs.luma.com/reference/post_v1-calendars-contact-tags-unapply.md): Unapply a tag from calendar contacts. Only affects existing contacts.
- [List Contact Tags](https://docs.luma.com/reference/get_v1-calendars-contact-tags-list.md)
- [Create Event Tag](https://docs.luma.com/reference/post_v1-calendars-event-tags-create.md)
- [Update Event Tag](https://docs.luma.com/reference/post_v1-calendars-event-tags-update.md)
- [Delete Event Tag](https://docs.luma.com/reference/post_v1-calendars-event-tags-delete.md)
- [Apply Event Tag](https://docs.luma.com/reference/post_v1-calendars-event-tags-apply.md): Apply a tag to events on the calendar.
- [Unapply Event Tag](https://docs.luma.com/reference/post_v1-calendars-event-tags-unapply.md): Unapply a tag from events on the calendar.
- [List Event Tags](https://docs.luma.com/reference/get_v1-calendars-event-tags-list.md)
- [Create Coupon](https://docs.luma.com/reference/post_v1-calendars-coupons-create.md): Create a coupon that can be applied to any event that is managed by the calendar. Be careful not to have the same code on an event and on the calendar.
- [Update Coupon](https://docs.luma.com/reference/post_v1-calendars-coupons-update.md)
- [List Calendar Coupons](https://docs.luma.com/reference/get_v1-calendars-coupons-list.md): List all coupons that have been created for a calendar.
- [List Membership Tiers](https://docs.luma.com/reference/get_v1-memberships-tiers-list.md): List available membership tiers for the calendar.
- [Add Member to Tier](https://docs.luma.com/reference/post_v1-memberships-members-add.md): Add a user to a membership tier. For paid tiers, set skip_payment to true if you are handling payment externally.
- [Update Member Status](https://docs.luma.com/reference/post_v1-memberships-members-update-status.md): Update a member's membership status. Approving a paid tier member captures their payment. Declining cancels any active subscription.
- [Create Webhook](https://docs.luma.com/reference/post_v2-webhooks-create.md): Create a new webhook endpoint to receive event notifications.
- [Update Webhook](https://docs.luma.com/reference/post_v2-webhooks-update.md): Update a webhook endpoint's event types or status (active/paused).
- [Get Webhook](https://docs.luma.com/reference/get_v2-webhooks-get.md): Get details about a specific webhook endpoint.
- [List Webhooks](https://docs.luma.com/reference/get_v1-webhooks-list.md): List all webhook endpoints for the calendar.
- [Delete Webhook](https://docs.luma.com/reference/post_v1-webhooks-delete.md): Delete a webhook endpoint.
- [Event Created](https://docs.luma.com/reference/webhook_event_created.md): Triggered when a new event is created on your calendar.
- [Event Updated](https://docs.luma.com/reference/webhook_event_updated.md): Triggered when an event's details are updated (name, time, location, etc.).
- [Event Canceled](https://docs.luma.com/reference/webhook_event_canceled.md): Triggered when an event is canceled.
- [Guest Registered](https://docs.luma.com/reference/webhook_guest_registered.md): Triggered when a guest registers for an event, including re-registrations after cancellation.
- [Guest Updated](https://docs.luma.com/reference/webhook_guest_updated.md): Triggered when a guest's registration is updated (approval status changed, answers updated, etc.).
- [Ticket Registered](https://docs.luma.com/reference/webhook_ticket_registered.md): Triggered when a ticket is purchased or registered. Includes ticket and guest details.
- [Calendar Person Subscribed](https://docs.luma.com/reference/webhook_calendar_person_subscribed.md): Triggered when someone subscribes to your calendar (becomes a follower).
- [Calendar Event Added](https://docs.luma.com/reference/webhook_calendar_event_added.md): Triggered when an event is added to a calendar — created on it, approved, transferred in, or made public. This can be a Luma event or an external event.
- [Calendar Event Submitted](https://docs.luma.com/reference/webhook_calendar_event_submitted.md): Triggered when an event is submitted to your calendar and is pending approval. This can be a Luma event or an external event. Use the `id` with the Approve Event or Reject Event endpoint to process the submission — with an organization API key, pass `submitted_to_calendar.id` as the `x-luma-calendar-id` header.
- [List Organization Admins](https://docs.luma.com/reference/get_v1-organizations-admins-list.md): List all admins for the organization.
- [List Organization Calendars](https://docs.luma.com/reference/get_v1-organizations-calendars-list.md): List all calendars belonging to the organization.
- [Create Calendar](https://docs.luma.com/reference/post_v2-organizations-calendars-create.md): Create a new calendar within the organization. The calendar will be managed by the API key owner.
- [List Organization Events](https://docs.luma.com/reference/get_v1-organizations-events-list.md): List all events across all calendars belonging to the organization. Events are deduplicated if they appear on multiple calendars within the organization.
- [Transfer Event Calendar](https://docs.luma.com/reference/post_v1-organizations-events-transfer-calendar.md): Transfer an event from its current managing calendar to a different calendar within the organization. The event's managing calendar changes to the destination calendar. Both the source and destination calendars must belong to the organization.
- [Get Self](https://docs.luma.com/reference/get_v1-users-get-self.md)
- [Lookup Entity](https://docs.luma.com/reference/get_v1-entities-lookup.md): Lookup an entity on Luma by its slug.
- [Create Upload URL](https://docs.luma.com/reference/post_v1-images-create-upload-url.md)