> ## Documentation Index
> Fetch the complete documentation index at: https://developers.momogood.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> A read-only HTTP surface for exporting Givergy event data into the systems you already run — CRMs, data warehouses, reporting tools, and custom destinations.
The Events & Auctions API gives third-party developers a read-only HTTP surface for exporting Givergy fundraising-event data — events, items, purchases, and guests — into the systems you already operate. Use it to keep your CRM, data warehouse, or internal reporting in sync with what's happening on the Givergy platform.
**Coming Soon — your custom integration.** Each endpoint family below was originally built for a specific customer's destination system. The same foundation lets us shape a new integration to your CRM, data warehouse, or internal stack — HubSpot, Microsoft Dynamics, NetSuite, Raiser's Edge, Snowflake, BigQuery, or anything else with a stable ingestion interface. Contact [support@givergy.com](mailto:support@givergy.com) to scope yours.
## How an integration is delivered
1. You tell us the destination system, the fields you need, the sync cadence, and the data-residency region.
2. We provision a service user, assign a namespace under `{EMS_BASE_URL}//v1/...`, and shape the payload to match your destination.
3. You point your sync job at the endpoints documented here. The behaviour — pagination, `since`-based polling, error shapes, enum casing — stays consistent across every integration we deliver.
## Integration families available today
We currently ship three integration shapes. Each is a working pattern in production for at least one customer; we extend or fork them for new engagements.
The richest, general-purpose export. Returns every available field — payment status, processor type, project segment, descriptive item metadata, and external reference IDs. Path namespace is assigned per integration. **The recommended shape when your destination can ingest the full payload.**
`/salesforce/v1/...` — payload shaped for native Salesforce ingestion (intentionally leaner than the Custom Data Export shape).
`/blackbaud/v1/...` — payload shaped for native Blackbaud ingestion (same trimmed shape as the Salesforce connector).
Every family requires a service user provisioned by Givergy. Contact [support@givergy.com](mailto:support@givergy.com) to set up your integration — whether you're enabling one of the existing shapes for your account or scoping a new one.
## Which family should I use?
| If you need… | Use |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Payment status, processor type, or project-segment fields | **Custom Data Export** |
| Descriptive item fields (description, terms, categories, IRS subcategories, bid increments, starting prices, tax rates, estimates) | **Custom Data Export** |
| Guest external IDs, SMS opt-in flag, or company name | **Custom Data Export** |
| Salesforce-shaped payload for native CRM ingestion | **Salesforce connector** |
| Blackbaud-shaped payload for native CRM ingestion | **Blackbaud connector** |
| Any other destination (HubSpot, Snowflake, internal warehouse, etc.) | Talk to us — we'll scope a new integration shape based on Custom Data Export |
## How the docs are organized
* **[Authentication](/events-auctions/authentication)** — session-cookie login flow, optional OTP, per-family authorization rules.
* **[Base URL and regions](/events-auctions/base-url-and-regions)** — the five regional hostnames in production today.
* **[Conventions](/events-auctions/conventions)** — money fields, timestamps, pagination, enum casing, content type.
* **[Rate limiting](/events-auctions/rate-limiting)** — plan for 1 request per second per integrator.
* **[Errors](/events-auctions/errors)** — JSON error shape and the status codes you'll see.
* **[Polling pattern](/events-auctions/polling-pattern)** — recommended sync flow using the `since` cursor.
* **[Limitations](/events-auctions/limitations)** — what the API doesn't do today, and what's on the roadmap.
* **Endpoints** — one page per resource (Events / Items / Purchases / Guests), with each family's variant shown side-by-side.
* **[Schemas](/events-auctions/schemas)** — `Event`, `ItemsBundle`, `PurchasesBundle`, `Guest`, `AddressDetail`, and the enums.
## Payload customization examples
The three families differ in **which fields each record carries**. Every family returns the same JSON wrapper shapes (`ItemsBundle` and `PurchasesBundle` have identical keys); the per-record fields are shaped to the destination. The table below shows what the Custom Data Export shape adds on top of the connector shapes — useful as a concrete example of the kind of customization we deliver per integration.
| Record type | Fields on Custom Data Export only (omitted from Salesforce / Blackbaud) |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Event` | `projectType`, `externalId` |
| `Guest` | `externalId`, `smsOptIn`, `companyName` |
| `BuyNowItem` | `revenueStreamType`, `externalId`, `categories`, `irsSubcategory`, `startPrice`, `increments`, `description`, `termsDescription`, `taxRate`, `estimate` |
| `AuctionItem` | `revenueStreamType`, `externalId`, `categories`, `irsSubcategory`, `startPrice`, `increments`, `type`, `description`, `termsDescription`, `estimate` |
| `Pledge` | (identical — no difference) |
| `Raffle` | `revenueStreamType` |
| `GliRaffle` | `revenueStreamType`, `externalId` |
| `Ticket` | `revenueStreamType`, `externalId` |
| `BuyNowPurchase` | `projectSegment`, `processorType`, `paymentStatus` |
| `AuctionBid` | `projectSegment`, `processorType`, `paymentStatus` |
| `RafflePurchase` | `projectSegment`, `processorType`, `paymentStatus` |
| `GliRafflePurchase` | `projectSegment`, `processorType`, `paymentStatus` |
| `TicketPurchase` | `projectSegment`, `processorType`, `paymentStatus` |
| `Donation` | `projectSegment`, `processorType`, `paymentStatus` |
For a new integration, we'd discuss the destination's schema and shape the payload to match — adding fields not shown here, dropping fields you don't need, or transforming values at the boundary.
## What's on the roadmap
**Coming Soon — new CRM and warehouse connectors.** New families on the same foundation as Salesforce and Blackbaud. If you have a destination in mind, [contact us](mailto:support@givergy.com) and we'll add it to the roadmap.
**Coming Soon — write/mutation endpoints.** The current API is read-only. Write capabilities (creating events, items, processing payments) are scoped per integration. Contact us to discuss your use case.
**Coming Soon — webhook notifications.** Push notifications for resource changes. Until then, use the [polling pattern](/events-auctions/polling-pattern) with `since`.
**Coming Soon — OAuth 2.0 and API-key authentication.** The current API uses session-cookie auth. Modern auth options are on the roadmap.
**Coming Soon — bulk and async export jobs.** For one-time large backfills, ask us about async export — useful when polling individual events at scale isn't the right shape.
## Glossary
A few terms used throughout the docs:
| Term | Meaning |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Event** (gala) | A fundraising event hosted on Givergy. The top-level container for items, purchases, and guests. |
| **Lot** | An auction item that guests bid on. |
| **Buy-now** | A fixed-price item guests can purchase immediately (no bidding). |
| **Pledge** | A donation ask. Can be fixed-amount or open-amount. |
| **Raffle** | A ticketed prize draw. |
| **GLI raffle** | A raffle regulated by Gaming Laboratories International. Compliance is handled separately from standard raffles. |
| **Ticket** | An event-entry ticket type (not a raffle ticket). |
| **Committed purchase** | A finalized transaction — distinct from active bids or pending payments. |
| **Winning bid** | The top bid on an auction item once the auction closes. |
| **Processor type** | The payment method used (Stripe, PayPal, cash, cheque, etc.). |
| **Revenue stream type** | An internal accounting category for items. |
| **Project segment** | A free-form reporting tag for grouping purchases. |
| **IRS subcategory** | A US-tax reporting classification for items. |
| **Gift Aid** | A UK-only HMRC mechanism letting charities reclaim tax on donations. |
| **Namespace** | The path prefix assigned to your integration (e.g. `/salesforce/v1`, `/blackbaud/v1`, or a custom prefix). |