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.

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

---

List Events

GET /open-events

List your events.

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.

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.

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.

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:

Event Types

Use these values for eventType fields:

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