PopUp Organizer

搜索并雇用移动供应商参加 PopUp 上的活动。查找美食车、DJ、照相亭等，创建活动列表、发送预订查询并管理发票。

## 概述（中文）

搜索并雇用移动供应商参加 PopUp 上的活动。查找美食车、DJ、照相亭等，创建活动列表、发送预订查询并管理发票。

## 原文

# PopUp Organizer

Search and hire mobile vendors — food trucks, DJs, photo booths, florists, live bands, and more — for any event. Create event listings, send booking inquiries, manage applications, track invoices, and save favorite vendors.

---

## Getting Started

1. Sign up or log in at <https://usepopup.com/login>
2. Switch to **Organizer** mode
3. Go to **Settings > API Keys**
4. Click **Create API Key** and copy the key (shown only once)

---

## Authentication

All requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer pk_live_...
```

The token is provided via the `POPUP_API_KEY` environment variable.

**Rate limit:** 60 requests per minute per API key. HTTP 429 is returned with `Retry-After: 60` if exceeded.

**Base URL:** `https://usepopup.com/api/v1/organizer`

---

## Endpoints

### Search Vendors

`GET /vendors`

Search published vendor profiles by name, type, location, event type, or price range.

| Param | Type | Description |
|-------|------|-------------|
| `q` | string | Search query (name, type, city, description) |
| `type` | string | Vendor category — see categories below |
| `state` | string | 2-letter US state code (e.g. `CA`, `NY`) |
| `metro` | string | Metro area within state (requires `state`) |
| `event` | string | Event type filter — see event types below |
| `price` | string | Price range: `$`, `$$`, `$$$`, `$$$$` |
| `sort` | string | `newest`, `name_asc`, `name_desc`, `rating` |
| `page` | number | Page number (default 1) |
| `limit` | number | Results per page (default 20, max 100) |

Returns vendor profiles with `businessName`, `businessType`, `homeCity`, `homeState`, `priceRange`, `averageRating`, `eventTypes`, `slug`, and more.

---

### List Events

`GET /open-events`

List your events.

| Param | Type | Description |
|-------|------|-------------|
| `status` | string | Filter: `open`, `closed`, `canceled` |
| `page` | number | Page number |
| `limit` | number | Results per page |

Returns events with `title`, `eventDate`, `startTime`, `endTime`, `eventCity`, `eventState`, `vendorCap`, `expectedGuestCount`, `status`, `shareUrl`, `shortUrl`, and `qrCodeUrl`.

### Get Event Detail

`GET /open-events/{eventId}`

Returns the event object plus an `applications` array (each with `businessId`, `status`, `quotedRate`, `engagementModel`, and nested `business` info) and `eventTerms`.

### Create Event

`POST /open-events`

Create a new event listing.

**Required fields:** `title`, `description`, `eventType`, `eventDate` (YYYY-MM-DD), `startTime` (HH:mm), `endTime` (HH:mm), `eventPlaceName`, `eventAddress1`, `eventCity`, `eventState` (2-letter), `eventZip`, `vendorCap` (1-1000), `feePayer` (`organizer_pays` | `vendor_pays` | `none`), `expectedGuestCount` (1-100000), `vendorCategoriesWanted` (array, 1-20 items).

**Optional fields:** `location`, `eventLat`, `eventLng`, `heroImageUrl`, `organizerBudget`, `boothFee`, `salesPercent`, `hiredBudget`, `venueSetting`, `requiresVerification`, `invoiceDueDays`, `termIds`.

Events are pending admin approval before becoming publicly visible.

### Update Event

`PATCH /open-events/{eventId}`

Update event fields or perform actions.

**Actions:** `{ "action": "close" }` to close to new applications, `{ "action": "reopen" }` to reopen.

**Updatable fields:** all the same fields as create. When key details change (date, time, venue, title), accepted vendors are notified.

### Cancel Event

`DELETE /open-events/{eventId}`

Cancel an event. All pending and accepted vendors are notified.

---

### List Applications

`GET /open-events/{eventId}/applications`

List vendor applications for an event.

| Param | Type | Description |
|-------|------|-------------|
| `status` | string | Filter: `pending`, `accepted`, `declined`, `withdrawn` |
| `page` | number | Page number |
| `limit` | number | Results per page |

### Get Event QR Code

`GET /open-events/{eventId}/qr`

Returns a PNG QR code image for the event share link.

---

### List Inquiries

`GET /inquiries`

List your inquiries to vendors.

| Param | Type | Description |
|-------|------|-------------|
| `status` | string | Filter: `pending`, `quoted`, `booked`, `declined` |
| `page` | number | Page number |
| `limit` | number | Results per page |

Returns inquiries with `eventDate`, `eventType`, `guestCount`, `location`, `budget`, `message`, `status`, `quotedPrice`, `quoteMessage`, and nested `business` info.

### Get Inquiry Detail

`GET /inquiries/{id}`

Get a single inquiry with full detail.

### Create Inquiry

`POST /inquiries`

Send a booking inquiry to a vendor.

**Required:** `businessId` (UUID).

**Optional:** `bookingType` (`catering` | `vending`), `eventDate` (YYYY-MM-DD), `eventType`, `guestCount`, `location`, `eventPlaceName`, `eventAddress1`, `eventCity`, `eventState`, `eventZip`, `budget`, `message`, `phone`, `startTime` (HH:mm), `endTime` (HH:mm), `estimatedPrice`.

The vendor is notified by email and in-app notification.

### Update Inquiry

`PATCH /inquiries/{id}`

Update a pending inquiry or respond to a quote.

**Actions:** `{ "action": "accept_quote" }` (inquiry must be `quoted`), `{ "action": "decline" }` (inquiry must be `quoted`).

**Updatable fields (pending only):** `eventDate`, `eventType`, `guestCount`, `location`, `budget`, `message`, `startTime`, `endTime`.

### Delete Inquiry

`DELETE /inquiries/{id}`

Delete a pending inquiry. Only works on `status=pending`.

---

### List Invoices

`GET /invoices`

List invoices for event applications and direct inquiries.

| Param | Type | Description |
|-------|------|-------------|
| `page` | number | Page number |
| `limit` | number | Results per page |

Returns invoices with `eventTitle`, `eventDate`, `vendorName`, `engagementModel`, `amount` (dollars), `direction` (`receivable` | `payable`), `isPaid`.

---

### List Saved Vendors

`GET /saved`

List your bookmarked vendors.

### Save Vendor

`POST /saved`

Bookmark a vendor: `{ "businessId": "..." }`

### Remove Saved Vendor

`DELETE /saved?businessId=...`

Remove a bookmarked vendor.

---

### Get Profile

`GET /profile`

Get your organizer profile and account info.

### Update Profile

`PATCH /profile`

Update your organizer profile.

**Fields:** `companyName`, `companyType` (`brand` | `agency` | `planner` | `corporate`), `eventTypes` (array), `location`, `city`, `state`, `zip`, `phone`, `website`, `about`, `givesBack`, `nonProfit`, `forACause`, `rules`.

---

## Response Format

All endpoints return JSON with `{ "data": ... }` wrapper. List endpoints include `{ "pagination": { "page", "limit", "total", "totalPages" } }`.

Error responses: `{ "error": "message" }` with appropriate HTTP status (400, 401, 404, 429, 500).

---

## Vendor Categories

Use these values for the `type` parameter when searching vendors:

| Value | Label |
|-------|-------|
| `food_truck` | Food |
| `bakery` | Bakery / Desserts |
| `beverage` | Beverage / Coffee / Bar |
| `dj` | DJ / Entertainment |
| `photo_booth` | Photo Booth |
| `photography` | Photography |
| `live_band` | Live Music |
| `florist` | Florist / Event Florals |
| `balloons` | Balloons / Balloon Decor |
| `yoga` | Wellness |
| `arts_crafts` | Retail Vendor |
| `other` | Other |

## Event Types

Use these values for `eventType` fields:

`wedding`, `corporate`, `birthday`, `festival`, `market`, `popup`, `fundraiser`, `community`, `holiday`, `private`, `other`