---
title: "Add guests in bulk with the API"
description: "Push guests from a spreadsheet or a CRM, up to 100 per call, with a result for each one."
canonical: https://app.ueventi.com/docs/en/articles/add-guests-in-bulk-with-the-api
last_updated: 2026-10-14
language: en
collection: "API & integrations"
---

# Add guests in bulk with the API

Push guests from a spreadsheet or a CRM, up to 100 per call, with a result for each one.

All collections: [API & integrations](https://app.ueventi.com/docs/en/api-and-integrations)

To add guests from another system, send them to **POST https://api.ueventi.com/v1/events/{id}/guests/batch** with a key that has the **Add guests** permission. Use the event id from the events list.

The body is a JSON object with a **guests** list of up to 100 entries and **"consent": true**. Each guest needs a **name** and a **phone** with its country code. **language**, **party_size_invited**, **side**, **group** and **custom_link** are optional, just like in the dashboard.

## What comes back

The response has one result per guest, in the same order you sent them. Each has a **status**: **201** means created (the body is the new guest with its personal invitation link), **400** means that row was invalid (the body lists which fields), **409** means a guest with that phone is already on the event. The call succeeds even if some rows failed, so check every result.

- To add a single guest, use **POST /v1/events/{id}/guests** with the same fields plus **consent**.
- Phone numbers are normalised to international format, so **+1 (512) 555-0142** and **+15125550142** are the same guest.
- Bigger lists go in several batches of 100. Send an **Idempotency-Key** header on each call so a retry after a timeout never creates duplicates.

## Consent

The **consent** field is the same attestation you make when importing in the dashboard: you confirm these guests agreed to receive your invitations and reminders. Without it the request is refused and nothing is written. See [Guest consent](https://app.ueventi.com/docs/en/articles/guest-consent).

> **Note:** Adding a guest through the API doesn't send anything. Messages go out according to the event's journey, exactly as for guests added in the dashboard.

## Related articles

- [Create an API key](https://app.ueventi.com/docs/en/articles/create-an-api-key.md): Make a key for a script or an AI agent, choose what it may do, and keep it safe.
- [Your first request and the sandbox](https://app.ueventi.com/docs/en/articles/your-first-request-and-the-sandbox.md): Try the API without a key in the sandbox, then make a real request with yours.
- [Export RSVPs with the API](https://app.ueventi.com/docs/en/articles/export-rsvps-with-the-api.md): Download the guest list with RSVP answers as a CSV, ready for a planner or a spreadsheet.