Skip to main content

Changelog

All notable consumer-facing changes to the Donorfy API are documented here.

What is recorded​

This changelog records observable changes to the REST API:

  • endpoints and routes,
  • request and response fields,
  • Basic authentication behaviour and the headers it requires,
  • conventions such as pagination, sorting, field inclusion and rate limiting, and the error contract.

It deliberately excludes anything integrators cannot observe in the REST contract: internal refactors, database and schema work, CI and infrastructure changes, dependency and package updates or security patch resolutions.

It is a contract log — not a per-deploy or per-pull-request log.

Format​

The format is based on Keep a Changelog. Entries are grouped under Added, Changed, Deprecated, Removed, Fixed or Security as appropriate.

Versioning and dating​

The API ships continuously through CI/CD, so releases are identified by date rather than a version number. Each section is dated by the production release date — the date the change becomes observable in production. Where several production releases happen on the same day, their changes are combined under a single dated heading.

For the full, always-current list of endpoints, request and response schemas, see Resources, which links to Swagger UI (/swagger/index.html) and the OpenAPI specification (/openapi/v1.json). Individual endpoints and verbs are not enumerated here.

[2026-09-29]​

Added​

  • GET /v1/transactions lists an instance's payments, with dateAdded and dateChanged filters, sorting, and include=allocations to expand each payment's allocations.
  • The constituent detail endpoint can now return a givingSummary include.
  • GET /v1/transactions/{transactionId} retrieves one of an instance's payments, always with the allocations that split it across products and funds, and with include=trackingCodes and include=softCredits to expand the payment's UTM tracking codes and the constituents soft credited with it.
  • giftAidStatusDetails on every payment returned by the transaction endpoints.
  • language on every lookup type returned by the lookup type endpoints, and a language filter on GET /v1/lookup-types that matches the language code exactly.
  • Gift Aid on POST /v1/transactions: giftAid.addDeclaration and giftAid.declarationMethod record a declaration for the donor; giftAid.claimed and giftAid.amountClaimed record tax already claimed elsewhere, which stops Donorfy claiming it again; and allocations[].canRecoverTax says whether tax can be recovered on each allocation.
  • UTM tracking codes on POST /v1/transactions: utmSource, utmMedium, utmTerm, utmContent and utmCampaign record the tracking codes for the payment, and are returned by include=trackingCodes on GET /v1/transactions/{transactionId}.
  • constituentNumber on each match returned by the constituent duplicate-check endpoint (POST /v1/constituents/duplicate-check).

Changed​

  • POST /v1/transactions returns the payment it created in full, in the same shape as GET /v1/transactions/{transactionId} without any includes, in place of the identifiers it returned before. The Location response header points at the new payment. mainContactConstituentId and giftAidDeclarationId are no longer returned: the main contact and the Gift Aid declaration are still created, and are read from the constituent.
  • POST /v1/constituents returns the constituent it created in the same shape as GET /v1/constituents/{constituentId}?include=channelPreferences, in place of the reduced body it returned before. The other includes (trackingCodes, contactDetails, givingSummary) are not returned; read the constituent with include= to get them. mainContact is unchanged and still describes the main contact created for a household or organisation.
  • POST /v1/lists returns the list definition it created in full, in the same shape as GET /v1/lists/{listDefinitionId}, in place of the listDefinitionId on its own. The identifier is still present, as listDefinitionId of the returned list definition, and the Location response header is unchanged.

[2026-09-12]​

Added​

  • Initial public release of the Donorfy REST API.
  • Constituents — read, create, update and delete constituents, check incoming records for duplicates, and read a constituent's nested contact details, tags and channel preferences.
  • Campaigns — read campaigns and campaign detail.
  • Transactions — create transactions.
  • Lists — manage list definitions, start and cancel list runs, read run history and run results, and read the available list types.
  • Lookups — read lookup values and the lookup types that group them.
  • Basic authentication using an Authorization: Basic header together with the X-API-Key tenant header.
  • Standard conventions across list endpoints: pagination, sorting, field inclusion and rate limiting.