---
description: GigOrganizer API integration for managing gigs, contracts, team members, payments, and taxes
globs: []
---

# GigOrganizer API

When the user asks about gigs, contracts, team members, bookings, invoices, payments, W-9s, or 1099s, use the GigOrganizer API.

## Auth
All requests: `Authorization: Bearer $GIGORGANIZER_API_TOKEN` to `https://gigorganizer.com`

## Tier Access
Check first: `GET /api/user/tier` → { tier, scope }
- **Free:** No API calls. Hand a prefilled public wizard link: `gigorganizer.com/create/<type>?prefill=<base64>` (see Prefill below).
- **Monthly Pro:** Same API access as Annual Pro — token scope (read vs full), not subscription tier, gates writes. For a new contract, hand a prefilled Pro-creator link: `gigorganizer.com/dashboard/create?type=<type>&prefill=<base64>`.
- **Annual Pro:** Same as Monthly Pro — both tiers may hold a full-scope token. Create directly via API, or hand the `dashboard/create?type=<type>&prefill=<base64>` link to review first.

### Prefill
`<type>`: musician, dj, comedian, magician, kids, circus, dancer, sound_technician. `<base64>` = base64 of a JSON object (standard or URL-safe). Allowed keys: `eventType`, `clientName`, `clientEmail`, `contactName`, `performerName`, `performerEmail`, `eventDate` (YYYY-MM-DD), `startTime`, `endTime`, `numberOfMusicians`, `venueName`, `venueAddress`, `feeAmount`, `depositPercent`, `depositMode`, `depositFixedAmount`, `depositDueDate` (YYYY-MM-DD). Everything else (and all free-form prose/clauses) is dropped server-side. `eventType` is case-sensitive — exact wizard preset label only (musician: `Wedding`, `Corporate`, `Private Party`, `Restaurant`, `Winery`, `University/Government`, `Hotel/Resort`, `Festival Performance`, `Club/Bar`, `Religious Institution`, `Fundraiser / Nonprofit`, `Other`); mismatch is dropped.

## Key Endpoints (scope: read=read-scope token, full=full-scope token; both scopes available to any paid Pro tier)

### Gigs
- `GET /api/purchases` — list all gigs
- `GET /api/purchase/session/{id}` — gig details
- `GET /api/credits` — check GigPack balance and use `access.canCreateContract` / `access.displayBalance` for decisions
- `POST /api/credits/use` — create contract using 1 GigPack (confirm with user first — never silently deduct). Returns purchaseId. Give user the purchase page URL to send for e-signature.
- No credits (`access.canCreateContract` false) → browser/dashboard action only; do NOT call `POST /api/checkout/esign` with a token (not token-authenticated — would create a guest checkout detached from the account). Direct user to https://gigorganizer.com/dashboard/create

### E-Signature
- Send for signing is a **dashboard action, not a token call** — hand the user the purchase page URL (`https://gigorganizer.com/purchase/session/{purchaseId}`) to send from there
- `GET /api/purchase/session/{id}/esign/db-status` — check status (read-only)
- Downloading the signed PDF (`GET .../esign/download`) is a **dashboard/guest action, not a token call** — it authenticates via session/guest cookie, so a PAT request 404s; send the user to the dashboard or their guest link to download

### Team
- `GET /api/purchase/session/{id}/musicians` — list roster
- `POST /api/purchase/session/{id}/musicians` — add member
- `POST /api/purchase/session/{id}/musicians/invite` — send invitations

### Payments
- `POST /api/purchase/session/{id}/payment-status` — mark deposit/balance paid
- `POST /api/purchase/session/{id}/documents/send` — send invoice/receipt
- `GET /api/dashboard/payments?start=&end=` — revenue summary

### Client
- `POST /api/purchase/session/{id}/email` — send contract email
- `POST /api/purchase/session/{id}/nudge-client` — send reminder

### Tax (read-only via token — W-9 requests and 1099 filing are dashboard-only)
- `GET /api/tax/team-members` — list with W-9/filing status (read)
- W-9 requests: **dashboard action, not a token call** — direct user to `gigorganizer.com/dashboard/tax/team`
- 1099 filing: direct user to `gigorganizer.com/dashboard/tax`

## Rules
- Confirm before sending emails
- Client signs first, performer second
- 5-min cooldown on team invitations
- 60-sec cooldown on document emails
- Receipts require payment marked as paid
- "team member" not "musician" in UI text