Conventions

The same conventions apply across every endpoint regardless of family (Custom Data Export, Salesforce, or Blackbaud).

Money fields

All amounts are integers in the event’s minor currency unit:

Pence for GBP (£1.50 → 150)
Cents for USD, CAD, AUD, HKD ($1.50 → 150)

The event’s currency is reported on the Event record’s currency field as an ISO 4217 code.

Timestamps

created and updated fields are Unix epoch seconds in UTC — not milliseconds.

{
  "created": 1709123456,
  "updated": 1714003200
}

For human-readable times, format these as UTC and convert to the event’s timezone (Event.timezone, an IANA timezone id) if displaying to end users.

IDs

UUIDs unless otherwise specified.

The `since` parameter

Parameter	Type	Default	Notes
`since`	long (epoch seconds)	`1606062358` (2020-11-12)	The server filters records by `updated >= since`. Use `-1` (or any past epoch) to backfill everything.

The default is a past epoch — leaving it off returns all records updated since that date, which for most accounts is effectively “everything.” Pass an explicit since value to scope the response to recently-updated records. See the polling pattern for the recommended way to use since for incremental sync.

The `q` parameter

A simple full-text search. Empty string disables search. For bundle endpoints (/items, /purchases), the same q filters each category (buy-nows, auction items, etc.) independently.

Pagination

Parameter	Type	Default	Notes
`offset`	int	`0`	Records to skip.
`limit`	int	`1000`	Page size. Maximum `1000`.

For bundle endpoints (/items, /purchases), offset and limit apply per category in the response, not across the whole bundle. The bundle’s wrapper structure (its keys) is constant; only the array contents grow or shrink.

Status filter

All list endpoints implicitly filter to records with ACTIVE status. Archived, inactive, pending, and obfuscated records are not returned.

Enum casing

Enum values returned by the API are serialized in lowercase:

{
  "status": "active",
  "processorType": "stripe",
  "paymentStatus": "paid",
  "giftAidStatus": "yes"
}

Older Givergy reference material may show uppercase enum values (e.g. ACTIVE, STRIPE). Those are incorrect — the wire format is lowercase. Code-generated clients that assume uppercase will not deserialize correctly.

Content type and compression

Header	Value
Response `Content-Type`	`application/json`
Response compression	gzip when `Accept-Encoding: gzip` is sent on the request
Response `ETag` / `Cache-Control`	Not emitted

None of these endpoints emit ETag or Cache-Control: max-age. For incremental sync, use the polling pattern with since, not HTTP caching.

Overview

Endpoints

Reference

Money fields

Timestamps

IDs

The `since` parameter

The `q` parameter

Status filter

Enum casing

Content type and compression

​Money fields

​Timestamps

​IDs

​The since parameter

​The q parameter

​Pagination

​Status filter

​Enum casing

​Content type and compression

Money fields

Timestamps

IDs

The `since` parameter

The `q` parameter

Pagination

Status filter

Enum casing

Content type and compression