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.

[Unreleased]​

Added​

  • POST /v1/constituents/activities records an activity against an existing constituent, with an activity type, date, optional campaign (by campaignId or name), confidentiality, notes, the activity type's extra fields (code1-code10, yesNo1-yesNo10, number1-number10, date1-date10), a linkUrl, the external references externalReference1-externalReference5 and the UTM tracking codes utmSource, utmMedium, utmTerm, utmContent and utmCampaign. It returns the created activity (the same model retrieving an activity by ID will return), with its location in the Location header.

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