> ## 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.

# Response schemas

> Event, ItemsBundle, PurchasesBundle, Guest, AddressDetail, and the enums returned across every endpoint.

Reference for every record type returned by the Events & Auctions API. Where the Custom Data Export and connector variants differ, the Custom Data Export variant is the superset — connector variants omit some fields (see [Payload customization examples](/events-auctions/overview#payload-customization-examples) for the full comparison).

Quick links:

* [`Event` (Custom Data Export variant)](#event-custom-data-export-variant)
* [`ItemsBundle`](#itemsbundle) — wrapper for items
  * [`BuyNowItem`](#buynowitem) · [`AuctionItem`](#auctionitem) · [`Pledge`](#pledge) · [`Raffle`](#raffle) · [`GliRaffle`](#gliraffle) · [`Ticket`](#ticket) · [`BidIncrement`](#bidincrement)
  * [Example `ItemsBundle` (Custom Data Export) response](#example-itemsbundle-custom-data-export-response)
* [`PurchasesBundle`](#purchasesbundle) — wrapper for purchases
  * [Common purchase fields](#common-purchase-fields) · [`BuyNowPurchase`](#buynowpurchase) · [`AuctionBid`](#auctionbid) · [`RafflePurchase`](#rafflepurchase) · [`GliRafflePurchase`](#glirafflepurchase) · [`TicketPurchase`](#ticketpurchase) · [`Donation`](#donation)
  * [Example `PurchasesBundle` (Custom Data Export) response](#example-purchasesbundle-custom-data-export-response)
* [`Guest` (Custom Data Export variant)](#guest-custom-data-export-variant) · [Connector guest variants](#guest-connector-variants-salesforce-and-blackbaud)
* [`AddressDetail`](#addressdetail)
* [Enums](#enums): [`Status`](#status-enum) · [`PaymentStatus`](#paymentstatus-enum) · [`ProcessorType`](#processortype-enum) · [`giftAidStatus`](#giftaidstatus-yesnoanswer)

***

## Event (Custom Data Export variant)

Returned by [`GET /<your-namespace>/v1/events`](/events-auctions/endpoints/events).

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Event id. |
| `name` | string | Event display name. |
| `status` | enum string | One of [`Status`](#status-enum). All listed events are `"active"`. |
| `inAidOf` | string \| null | Beneficiary description. |
| `startTime` | long (epoch s) | Event start. |
| `endTime` | long (epoch s) | Event end. |
| `eventDate` | long (epoch s) | Headline event date used for sorting/display. |
| `timezone` | string | IANA timezone id (e.g. `Europe/London`, `America/New_York`). |
| `currency` | string | ISO 4217 currency code (`GBP`, `USD`, `CAD`, `AUD`, `HKD`). |
| `created` | long (epoch s) | When the event was created. |
| `updated` | long (epoch s) | When the event was last updated. |
| `projectType` | string | EMS project type code (e.g. `auction`, `mixed`). **Custom Data Export only.** |
| `externalId` | string \| null | Client-supplied external reference. **Custom Data Export only.** |

> The Salesforce/Blackbaud `Event` variant (not returned by any documented endpoint today, but useful background) would omit `projectType` and `externalId`.

***

## ItemsBundle

```json theme={null}
{
  "buyNows":      [ BuyNowItem, ... ],
  "auctionItems": [ AuctionItem, ... ],
  "pledges":      [ Pledge, ... ],
  "prizeDraws":   [ Raffle, ... ],
  "gliRaffles":   [ GliRaffle, ... ],
  "tickets":      [ Ticket, ... ]
}
```

`prizeDraws` holds standard `Raffle` records; `gliRaffles` is a separate list because GLI-regulated raffles have distinct compliance handling.

The wrapper shape is identical across all three families; the difference is in the per-record fields (see [Payload customization examples](/events-auctions/overview#payload-customization-examples)).

### BuyNowItem

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Item id. |
| `eventId` | UUID | Parent event. |
| `number` | string | Display / catalogue number. |
| `title` | string | Item name. |
| `price` | long | Unit price (minor units). |
| `available` | int | Inventory remaining. |
| `bought` | int | Quantity sold to date. |
| `requirePayment` | boolean | Whether checkout enforces payment. |
| `created` | long (epoch s) | Creation timestamp. |
| `updated` | long (epoch s) | Last-update timestamp. |
| `revenueStreamType` | string | EMS revenue stream code. *(Custom Data Export only)* |
| `externalId` | string \| null | Client reference. *(Custom Data Export only)* |
| `categories` | string\[] | Category tags. *(Custom Data Export only)* |
| `irsSubcategory` | string\[] | IRS reporting subcategories. *(Custom Data Export only)* |
| `startPrice` | long | Suggested / starting price (minor units). *(Custom Data Export only)* |
| `increments` | [`BidIncrement`](#bidincrement)\[] | Pricing tiers, where applicable. *(Custom Data Export only)* |
| `description` | string \| null | Long description. *(Custom Data Export only)* |
| `termsDescription` | string \| null | T\&Cs text. *(Custom Data Export only)* |
| `taxRate` | double \| null | Tax rate as decimal (`0.2` = 20%). *(Custom Data Export only)* |
| `estimate` | long \| null | Estimated value (minor units). *(Custom Data Export only)* |

The Salesforce/Blackbaud `BuyNowItem` variants include only the first 10 fields (down to `updated`).

### AuctionItem

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Lot id. |
| `eventId` | UUID | Parent event. |
| `number` | string | Lot number. |
| `title` | string | Lot title. |
| `currentAmount` | long | Current top bid (minor units). |
| `topBidder` | string \| null | Top bidder name. Null when anonymous. |
| `topBidAnonymous` | boolean | Whether the top bid is anonymous. |
| `created` | long (epoch s) | Creation timestamp. |
| `updated` | long (epoch s) | Last-update timestamp. |
| `revenueStreamType` | string | EMS revenue stream code. *(Custom Data Export only)* |
| `externalId` | string \| null | Client reference. *(Custom Data Export only)* |
| `categories` | string\[] | Category tags. *(Custom Data Export only)* |
| `irsSubcategory` | string\[] | IRS reporting subcategories. *(Custom Data Export only)* |
| `startPrice` | long | Opening bid (minor units). *(Custom Data Export only)* |
| `increments` | [`BidIncrement`](#bidincrement)\[] | Bid increment tiers. *(Custom Data Export only)* |
| `type` | string | Auction type code (e.g. `STANDARD`). *(Custom Data Export only)* |
| `description` | string \| null | Description text. *(Custom Data Export only)* |
| `termsDescription` | string \| null | T\&Cs text. *(Custom Data Export only)* |
| `estimate` | long \| null | Estimated value (minor units). *(Custom Data Export only)* |

### Pledge

Identical across all three families.

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Pledge id. |
| `eventId` | UUID | Parent event. |
| `number` | string | Display number. |
| `title` | string | Pledge title. |
| `minimum` | long | Minimum donation (minor units). |
| `fixed` | boolean | `true` = fixed donation amount; `false` = open amount. |
| `created` | long (epoch s) | Creation timestamp. |
| `updated` | long (epoch s) | Last-update timestamp. |

### Raffle

| Field | Type | Description |
| - | - | - |
| `id` | string (UUID format) | Raffle id. |
| `eventId` | UUID | Parent event. |
| `number` | string | Display number. |
| `title` | string | Raffle title. |
| `price` | long | Ticket price (minor units). |
| `available` | int | Tickets remaining. |
| `bought` | int | Tickets sold. |
| `requirePayment` | boolean | Whether checkout enforces payment. |
| `created` | long (epoch s) | Creation timestamp. |
| `updated` | long (epoch s) | Last-update timestamp. |
| `revenueStreamType` | string | EMS revenue stream code. *(Custom Data Export only)* |

Connector variants omit `revenueStreamType` only.

### GliRaffle

All fields from [`Raffle`](#raffle), **plus** `externalId` (string | null, Custom Data Export only). GLI-regulated raffles (Gaming Laboratories International) are reported separately for compliance.

Connector variants omit `revenueStreamType` and `externalId`.

### Ticket

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Ticket type id. |
| `eventId` | UUID | Parent event. |
| `title` | string | Ticket name. |
| `price` | long | Ticket price (minor units). |
| `maxPerPurchase` | int | Per-order cap. |
| `available` | int | Tickets remaining. |
| `bought` | int | Tickets sold. |
| `created` | long (epoch s) | Creation timestamp. |
| `updated` | long (epoch s) | Last-update timestamp. |
| `revenueStreamType` | string | EMS revenue stream code. *(Custom Data Export only)* |
| `externalId` | string \| null | Client reference. *(Custom Data Export only)* |

### BidIncrement

A single tier of a bid-increment ladder.

| Field | Type | Description |
| - | - | - |
| `threshold` | long (≥0) | Lower bound (minor units) at which this increment applies. `0` means the increment applies from the opening bid. |
| `amount` | long (≥1) | The minimum bid step (minor units) when the current price is at or above `threshold`. |

<Warning>
  Some earlier Givergy reference material used `from` / `increment` for these field names. The actual JSON field names are `threshold` and `amount`. Trust this document over older examples.
</Warning>

### Example `ItemsBundle` (Custom Data Export) response

```json theme={null}
{
  "buyNows": [
    {
      "id": "b1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "BN-001",
      "title": "Signed Football",
      "price": 5000,
      "available": 8,
      "bought": 2,
      "requirePayment": true,
      "created": 1709200000,
      "updated": 1714100000,
      "revenueStreamType": "merchandise",
      "externalId": "EXT-BN-001",
      "categories": ["sports", "memorabilia"],
      "irsSubcategory": ["sports_collectibles"],
      "startPrice": 5000,
      "increments": [],
      "description": "Football signed by the 2025 squad.",
      "termsDescription": "No refunds.",
      "taxRate": 0.2,
      "estimate": 7500
    }
  ],
  "auctionItems": [
    {
      "id": "a1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "L-001",
      "title": "Weekend Stay in Paris",
      "currentAmount": 120000,
      "topBidder": "Jane Doe",
      "topBidAnonymous": false,
      "created": 1709200000,
      "updated": 1714200000,
      "revenueStreamType": "auction",
      "externalId": "EXT-L-001",
      "categories": ["travel"],
      "irsSubcategory": ["travel_packages"],
      "startPrice": 50000,
      "increments": [
        { "threshold": 0,      "amount": 5000 },
        { "threshold": 100000, "amount": 10000 }
      ],
      "type": "STANDARD",
      "description": "Two nights at a 4-star hotel in central Paris.",
      "termsDescription": "Subject to availability.",
      "estimate": 150000
    }
  ],
  "pledges": [
    {
      "id": "p1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "PL-001",
      "title": "Sponsor a Meal",
      "minimum": 1000,
      "fixed": false,
      "created": 1709200000,
      "updated": 1709200000
    }
  ],
  "prizeDraws": [
    {
      "id": "r1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "PD-001",
      "title": "Win a Tesla",
      "price": 2500,
      "available": 500,
      "bought": 124,
      "requirePayment": true,
      "created": 1709200000,
      "updated": 1714050000,
      "revenueStreamType": "raffle"
    }
  ],
  "gliRaffles": [
    {
      "id": "g1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "number": "GLI-001",
      "title": "50/50 Draw",
      "price": 2000,
      "available": 1000,
      "bought": 312,
      "requirePayment": true,
      "created": 1709200000,
      "updated": 1714100000,
      "revenueStreamType": "gli_raffle",
      "externalId": "EXT-GLI-001"
    }
  ],
  "tickets": [
    {
      "id": "t1a2c3d4-0001-4000-8000-000000000001",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "title": "Standard Entry",
      "price": 7500,
      "maxPerPurchase": 10,
      "available": 200,
      "bought": 47,
      "created": 1709200000,
      "updated": 1714000000,
      "revenueStreamType": "ticket",
      "externalId": "EXT-T-STD"
    }
  ]
}
```

***

## PurchasesBundle

```json theme={null}
{
  "buyNowPurchases":    [ BuyNowPurchase, ... ],
  "winningBids":        [ AuctionBid, ... ],
  "donations":          [ Donation, ... ],
  "rafflePurchases":    [ RafflePurchase, ... ],
  "gliRafflePurchases": [ GliRafflePurchase, ... ],
  "ticketPurchases":    [ TicketPurchase, ... ]
}
```

All purchase records share a common set of fields. Each subtype adds a small number of type-specific fields.

### Common purchase fields

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Purchase id. |
| `eventId` | UUID | Parent event. |
| `guestId` | UUID | Guest who made the purchase. |
| `guestName` | string | Guest display name. Empty string when anonymous. |
| `anonymous` | boolean | Whether the guest chose to remain anonymous. |
| `amount` | long | Gross amount (minor units). |
| `count` | int | Quantity. Not present on `AuctionBid` (a winning bid is always 1). |
| `totalFeesAmount` | long | Total fees retained from `amount`. |
| `totalFeesPassedOnAmount` | long | Fees added on top, paid by the guest. |
| `paymentProcessorId` | string \| null | Processor's transaction reference (e.g. Stripe payment intent id). |
| `created` | long (epoch s) | Creation timestamp. |
| `updated` | long (epoch s) | Last-update timestamp. |

The following three fields are present **only on the Custom Data Export variants**. They are absent from every purchase record returned by the Salesforce and Blackbaud connector endpoints.

| Field | Type | Description |
| - | - | - |
| `projectSegment` | string \| null | Reporting segment (free-form). *(Custom Data Export only)* |
| `processorType` | enum | One of [`ProcessorType`](#processortype-enum). *(Custom Data Export only)* |
| `paymentStatus` | enum | One of [`PaymentStatus`](#paymentstatus-enum). *(Custom Data Export only)* |

### Type-specific fields

| Type | Wrapper key | Extra fields |
| - | - | - |
| [`BuyNowPurchase`](#buynowpurchase) | `buyNowPurchases` | `buyNowItemId`, `buyNowItemTitle`, `supplyPrice` |
| [`AuctionBid`](#auctionbid) | `winningBids` | `auctionItemId`, `auctionItemTitle`, `calculatedAmount`, `supplyPrice` (no `count` field) |
| [`RafflePurchase`](#rafflepurchase) | `rafflePurchases` | `raffleId`, `raffleTitle`, `winningCount` |
| [`GliRafflePurchase`](#glirafflepurchase) | `gliRafflePurchases` | `raffleId`, `raffleTitle`, `winningCount` |
| [`TicketPurchase`](#ticketpurchase) | `ticketPurchases` | `ticketId`, `ticketTitle`, `ticketPurchaseRef`, `bookingFeeAmount`, `bookingFeePassedOnAmount` |
| [`Donation`](#donation) | `donations` | `pledgeId`, `pledgeTitle`, `giftAidStatus` |

### BuyNowPurchase

Common purchase fields plus:

| Field | Type | Description |
| - | - | - |
| `buyNowItemId` | UUID | Reference to the `BuyNowItem`. |
| `buyNowItemTitle` | string | Item title. |
| `supplyPrice` | long | Cost of supply (minor units). |

### AuctionBid

Common purchase fields plus:

| Field | Type | Description |
| - | - | - |
| `auctionItemId` | UUID | Reference to the `AuctionItem`. |
| `auctionItemTitle` | string | Lot title. |
| `calculatedAmount` | long | Calculated final amount (minor units). |
| `supplyPrice` | long | Cost of supply (minor units). |

**No `count` field** — a winning bid is always 1.

### RafflePurchase

Common purchase fields plus:

| Field | Type | Description |
| - | - | - |
| `raffleId` | UUID | Reference to the `Raffle`. |
| `raffleTitle` | string | Raffle title. |
| `winningCount` | int | Number of winning tickets in this purchase. |

### GliRafflePurchase

Same fields as `RafflePurchase`, returned under the `gliRafflePurchases` key. GLI raffles are reported separately for compliance.

### TicketPurchase

Common purchase fields plus:

| Field | Type | Description |
| - | - | - |
| `ticketId` | UUID | Reference to the `Ticket`. |
| `ticketTitle` | string | Ticket name. |
| `ticketPurchaseRef` | string | Human-readable booking reference (e.g. `TKT-2026-00047`). |
| `bookingFeeAmount` | long | Booking fee retained (minor units). |
| `bookingFeePassedOnAmount` | long | Booking fee added on top, paid by the guest (minor units). |

### Donation

Common purchase fields plus:

| Field | Type | Description |
| - | - | - |
| `pledgeId` | UUID | Reference to the `Pledge`. |
| `pledgeTitle` | string | Pledge title. |
| `giftAidStatus` | enum string | One of [`giftAidStatus`](#giftaidstatus-yesnoanswer): `not_asked`, `yes`, `no`. |

### Example `PurchasesBundle` (Custom Data Export) response

```json theme={null}
{
  "buyNowPurchases": [
    {
      "id": "c0000001-0000-4000-8000-000000000001",
      "buyNowItemId": "b1a2c3d4-0001-4000-8000-000000000001",
      "buyNowItemTitle": "Signed Football",
      "anonymous": false,
      "guestId": "f0000001-0000-4000-8000-000000000001",
      "guestName": "Alice Smith",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 5000,
      "count": 1,
      "totalFeesAmount": 150,
      "totalFeesPassedOnAmount": 0,
      "paymentProcessorId": "pi_3OabcDEFghi",
      "supplyPrice": 2000,
      "created": 1713900000,
      "updated": 1713900000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "winningBids": [
    {
      "id": "c0000002-0000-4000-8000-000000000002",
      "auctionItemId": "a1a2c3d4-0001-4000-8000-000000000001",
      "auctionItemTitle": "Weekend Stay in Paris",
      "anonymous": false,
      "guestId": "f0000002-0000-4000-8000-000000000002",
      "guestName": "Bob Jones",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 120000,
      "calculatedAmount": 120000,
      "totalFeesAmount": 3600,
      "totalFeesPassedOnAmount": 0,
      "paymentProcessorId": "pi_3OxyzABCdef",
      "supplyPrice": 60000,
      "created": 1714200000,
      "updated": 1714200000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "donations": [
    {
      "id": "c0000004-0000-4000-8000-000000000004",
      "pledgeId": "p1a2c3d4-0001-4000-8000-000000000001",
      "pledgeTitle": "Sponsor a Meal",
      "anonymous": false,
      "guestId": "f0000004-0000-4000-8000-000000000004",
      "guestName": "Carol White",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 2500,
      "count": 1,
      "totalFeesAmount": 75,
      "totalFeesPassedOnAmount": 0,
      "paymentProcessorId": "pi_3OdonLMNopq",
      "giftAidStatus": "yes",
      "created": 1714100000,
      "updated": 1714100000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "rafflePurchases": [
    {
      "id": "c0000003-0000-4000-8000-000000000003",
      "raffleId": "r1a2c3d4-0001-4000-8000-000000000001",
      "raffleTitle": "Win a Tesla",
      "winningCount": 0,
      "anonymous": true,
      "guestId": "f0000003-0000-4000-8000-000000000003",
      "guestName": "",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 5000,
      "count": 2,
      "totalFeesAmount": 0,
      "totalFeesPassedOnAmount": 150,
      "paymentProcessorId": "pi_3OrafFGHijk",
      "created": 1714050000,
      "updated": 1714050000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "gliRafflePurchases": [
    {
      "id": "c0000006-0000-4000-8000-000000000006",
      "raffleId": "g1a2c3d4-0001-4000-8000-000000000001",
      "raffleTitle": "50/50 Draw",
      "winningCount": 0,
      "anonymous": false,
      "guestId": "f0000006-0000-4000-8000-000000000006",
      "guestName": "Eve Green",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 4000,
      "count": 2,
      "totalFeesAmount": 0,
      "totalFeesPassedOnAmount": 120,
      "paymentProcessorId": "pi_3OgliWXYzab",
      "created": 1714100000,
      "updated": 1714100000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ],
  "ticketPurchases": [
    {
      "id": "c0000005-0000-4000-8000-000000000005",
      "ticketId": "t1a2c3d4-0001-4000-8000-000000000001",
      "ticketTitle": "Standard Entry",
      "ticketPurchaseRef": "TKT-2026-00047",
      "guestId": "f0000005-0000-4000-8000-000000000005",
      "guestName": "David Black",
      "eventId": "8f3c2a1d-9b4e-4c7a-a1d2-6e5f4c3b2a10",
      "amount": 15000,
      "count": 2,
      "bookingFeeAmount": 0,
      "bookingFeePassedOnAmount": 450,
      "totalFeesAmount": 450,
      "totalFeesPassedOnAmount": 450,
      "paymentProcessorId": "pi_3OtktRSTuvw",
      "created": 1713800000,
      "updated": 1713800000,
      "projectSegment": "main",
      "processorType": "stripe",
      "paymentStatus": "paid"
    }
  ]
}
```

> A Salesforce or Blackbaud `/purchases` response would be **the same shape**, but every record would have `projectSegment`, `processorType`, and `paymentStatus` removed.

***

## Guest (Custom Data Export variant)

Returned by the Custom Data Export `/guests` endpoint.

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Guest (contact) id. |
| `eventId` | UUID | Parent event. |
| `firstName` | string \| null | First name. |
| `lastName` | string \| null | Last name. |
| `email` | string \| null | Email address. |
| `mobile` | string \| null | Mobile phone. May be E.164 or local format depending on how it was captured. |
| `mainAddress` | [`AddressDetail`](#addressdetail) \| null | Primary postal address. |
| `giftAidAddress` | [`AddressDetail`](#addressdetail) \| null | Gift Aid declaration address (UK). |
| `taxReceiptAidAddress` | [`AddressDetail`](#addressdetail) \| null | Tax-receipt address (US). |
| `created` | long (epoch s) | Creation timestamp. |
| `updated` | long (epoch s) | Last-update timestamp. |
| `consentAsked` | boolean | Whether the guest has been prompted for consent. |
| `consentStatus` | enum string | One of [`Status`](#status-enum); typically `"active"` or `"inactive"` for consent records. |
| `consentChannels` | string | Comma-separated channels the guest has opted in to (e.g. `email,sms,post`). Empty string when none. |
| `externalId` | string \| null | Client reference. *(Custom Data Export only)* |
| `smsOptIn` | boolean | SMS opt-in flag. *(Custom Data Export only)* |
| `companyName` | string \| null | Company / organisation name. *(Custom Data Export only)* |

### Guest connector variants (Salesforce and Blackbaud)

`SalesforceGuest` (returned by `/salesforce/v1/.../guests`) and `BlackbaudGuest` (returned by `/blackbaud/v1/.../guests`) are **identical to each other** and contain every field from the Custom Data Export `Guest` **except** `externalId`, `smsOptIn`, and `companyName`.

If you need any of those three fields, you must use the Custom Data Export `/guests` endpoint.

***

## AddressDetail

| Field | Type | Description |
| - | - | - |
| `name` | string \| null | Label (e.g. `Home`, `Billing`). |
| `line1` | string \| null | First address line. |
| `line2` | string \| null | Second address line. |
| `line3` | string \| null | Third address line. |
| `line4` | string \| null | Fourth address line. |
| `town` | string \| null | Town / city. |
| `postcode` | string \| null | Postal / ZIP code. |
| `state` | string \| null | State / province / region. |
| `country` | string \| null | ISO 3166-1 alpha-2 country code (e.g. `GB`, `US`, `CA`, `AU`, `HK`). |
| `recipient_name` | string \| null | Recipient name. |

<Warning>
  Note the snake\_case spelling: the field is `recipient_name`, not `recipientName`. This is the only snake\_case field across these schemas.
</Warning>

***

## Enums

All enum values are serialized in **lowercase** in JSON. See [Conventions → Enum casing](/events-auctions/conventions#enum-casing).

### Status enum

Returned for `Event.status` and `Guest.consentStatus`. Values:

`error`, `archived`, `active`, `inactive`, `not_archived`, `obfuscated`, `pending`

In practice list endpoints only ever return records with `status: "active"` because of the implicit active-only filter.

### PaymentStatus enum

Returned on Custom Data Export purchase records only.

| Value | Meaning |
| - | - |
| `unknown` | Status not yet determined. |
| `paid` | Payment captured in full. |
| `unpaid` | Awaiting payment. |
| `part_paid` | Partial payment received. |
| `retracted` | Payment retracted. |
| `overpaid` | Payment exceeds the amount due. |
| `processor_pending` | Processor is still processing the payment. |
| `processor_declined` | Processor declined the payment. |
| `user_canceled` | Guest cancelled before payment. |
| `split` | Amount split across multiple records / processors. |
| `pay_later` | Payment deferred (will settle later). |

For most reporting use cases, treat `paid`, `part_paid`, `overpaid`, and `split` as "money received."

### ProcessorType enum

Returned on Custom Data Export purchase records only.

`none`, `paypal`, `paypal_here`, `cheque_client`, `cheque_ibid`, `cash_client`, `cash_ibid`, `bank_transfer_client`, `bank_transfer_ibid`, `braintree`, `braintree_amex`, `braintree_vt`, `braintree_vt_amex`, `stripe`, `daf_pay`, `stripe_amex`, `stripe_vt`, `stripe_vt_amex`, `pdq`, `pdq_amex`, `eftpos`, `amex`, `zero_amount_charge`, `free`

Conventions:

* The `_vt` suffix indicates a virtual terminal (typed-in card).
* `_client` variants indicate funds collected directly by the client.
* `_ibid` variants indicate funds collected by Givergy on the client's behalf.

### giftAidStatus (YesNoAnswer)

`Donation.giftAidStatus` is a tri-state string answering "has the guest agreed to Gift Aid this donation?"

| Value | Meaning |
| - | - |
| `not_asked` | The guest has not been asked, or Gift Aid is not applicable. |
| `yes` | Guest has agreed and a Gift Aid declaration is on file. |
| `no` | Guest has declined Gift Aid. |

<Warning>
  Earlier Givergy reference material listed values like `CLAIMED`, `PENDING`, `NOT_REQUESTED`. Those are incorrect — the wire values are the three above.
</Warning>

Gift Aid is a UK-only HMRC mechanism, so this field is most meaningful for UK events.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.