Donately API Reference

Overview

The Donately API is a RESTful JSON API for managing donations, campaigns, donors, and fundraisers on the Donately platform. All requests use the base URL:

https://api.donately.com/v2

All request and response bodies use JSON. Set the Content-Type: application/json header for requests with a body.

ID Format

All Donately resources use unique identifiers with a type prefix:

act_ — Accounts
cmp_ — Campaigns
dnt_ — Donations
sub_ — Subscriptions
per_ — People / Contacts
fun_ — Fundraisers
frm_ — Forms
hok_ — Webhooks

Authentication

Authenticate requests using your API token with HTTP Basic Auth. Encode your token as base64 with a trailing colon:

Authorization: Basic {base64(YOUR_API_TOKEN + ':')}

You can find your API token in the Donately dashboard under Settings → API.

Account Scoping

Most endpoints require specifying which account to query. Pass the account ID as a header or query parameter:

Donately-Account: act_ba7d12ab27bb
# or
?account_id=act_ba7d12ab27bb

Some endpoints (like creating a donation or viewing public campaigns) work without authentication for public-facing use.

Versioning

The API uses date-based versioning. Specify the version via the Donately-Version header:

Donately-Version: 2022-12-15

If no version header is sent, the API defaults to 2019-03-15. We recommend explicitly setting the version header in all requests.

v2019-03-15

The original and default API version. If no Donately-Version header is sent, this version is used. It includes all core resources:

Accounts, Campaigns, Donations, Subscriptions
People (donors/contacts), Fundraisers, Forms
Webhooks

This version is stable and widely used. All endpoints documented below are available in this version.

v2022-12-15

The latest API version with improvements to response formats and additional capabilities. All v2019-03-15 endpoints remain available.

What changed

Standardized response envelope — All list endpoints return a consistent { object, data, summary, params } structure
Request IDs — Every response includes a request_id field for debugging and support
Improved error format — Error responses now include type, message, code, and request_id
Native integration support — Accounts include native integration configuration (Salesforce, HubSpot, Mailchimp, etc.)
Enhanced webhook payloads — Webhook event payloads include richer data and consistent formatting
Subscription improvements — Additional fields for payment method details and retry status on subscriptions
Donation metadata — Expanded meta_data support on donations with custom field tracking

To use this version, include Donately-Version: 2022-12-15 in every request. The endpoint paths and parameters are the same as v2019-03-15.

Pagination & Filtering

All list endpoints support pagination and filtering via query parameters.

Pagination

Parameter	Description
limit	Number of records to return. Max `100`, default varies by endpoint.
offset	Number of records to skip. Default `0`.

Sorting

Parameter	Description
sort	`ASC` or `DESC`
order_by	Field to sort by, e.g. `created_at`, `amount_in_cents`

Standard Response Envelope

{
  "object": "list",
  "data": [ ... ],
  "summary": {
    "total_count": 142,
    "offset": 0,
    "limit": 20
  },
  "params": {
    "account_id": "act_ba7d12ab27bb",
    "api_version": "2022-12-15",
    "limit": 20,
    "offset": 0
  },
  "request_id": "req_1234567890123"
}

Errors

Error responses follow a consistent format:

{
  "type": "bad_request",
  "message": "Description of what went wrong",
  "code": "400",
  "request_id": "req_1234567890123"
}

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request — missing or invalid parameters
401	Unauthorized — invalid or missing API token
403	Forbidden — authenticated but insufficient permissions
404	Not Found
422	Unprocessable — validation errors
429	Rate Limited — too many requests
500	Internal Server Error

Accounts

Accounts represent organizations on Donately. Each account has its own campaigns, donors, forms, and settings.

GET /v2/accounts List accounts

Returns accounts accessible to the authenticated user.

Parameter	Description
limit	Results per page (max 100)
offset	Pagination offset

GET /v2/accounts/:id Get account

Retrieve a single account by its unique identifier. Public account info is available without authentication.

GET /v2/accounts/mine Get current account

Returns the account associated with the authenticated API token.

POST /v2/accounts Create account

Create a new Donately account.

POST /v2/accounts/:id Update account

Update an existing account's settings.

Campaigns

Campaigns are fundraising initiatives within an account. They can be general donation campaigns, peer-to-peer campaigns, or event-based campaigns.

GET /v2/campaigns List campaigns

Returns campaigns for the specified account. Public campaigns are accessible without authentication.

Parameter	Description
account_id required	Account identifier
status optional	`draft`, `published`, or `archived`
type optional	Campaign type filter (e.g. `peer_to_peer`, `donation`)
keyword optional	Search by title or content
has_fundraisers optional	Filter to campaigns with fundraisers
limit	Results per page (max 100)
offset	Pagination offset
sort	`ASC` or `DESC`
order_by	Sort field

GET /v2/campaigns/:id Get campaign

Retrieve a single campaign by unique identifier. Public campaigns can be accessed without authentication.

POST /v2/campaigns Create campaign

Create a new campaign for the specified account. Requires authentication.

POST /v2/campaigns/:id Update campaign

Update an existing campaign.

DELETE /v2/campaigns/:id Delete campaign

Delete a campaign. This action cannot be undone.

Donations

Donations represent individual gifts made through the platform. They can be one-time or recurring, and support multiple payment methods.

GET /v2/donations List donations

Returns donations for the specified account. Requires authentication.

Parameter	Description
account_id required	Account identifier
status optional	`completed`, `pending`, `refunded`, `rejected`
person_id optional	Filter by donor
campaign_id optional	Filter by campaign
fundraiser_id optional	Filter by fundraiser
donation_type optional	`cc` or `cash_or_check`
recurring optional	`true` or `false`
anonymous optional	`true` or `false`
currency optional	ISO currency code (e.g. `usd`, `cad`)
keyword optional	Text search
amount_in_cents optional	Filter by amount
created optional	Date range filter: `{gt: timestamp, lt: timestamp}`
updated optional	Date range filter: `{gt: timestamp, lt: timestamp}`
limit	Results per page (max 100)
offset	Pagination offset
sort	`ASC` or `DESC`
order_by	Sort field (e.g. `created_at`, `amount_in_cents`)

GET /v2/donations/:id Get donation

Retrieve a single donation by unique identifier.

POST /v2/donations Create donation

Create a new donation. This endpoint can be used without authentication for public campaign donations (typically called from the embeddable form).

Parameter	Description
account_id required	Account identifier
amount_in_cents required	Donation amount in cents
campaign_id optional	Campaign to attribute donation to
fundraiser_id optional	Fundraiser to attribute donation to
first_name optional	Donor first name
last_name optional	Donor last name
email optional	Donor email address
currency optional	ISO currency code (default: `usd`)
anonymous optional	Mark as anonymous donation
comment optional	Donor comment
on_behalf_of optional	Name of honoree
meta_data optional	Custom metadata (JSON object)

POST /v2/donations/:id Update donation

Update an existing donation record.

POST /v2/donations/:id/refund Refund donation

Refund a donation. This will process a refund through the original payment processor (Stripe or PayPal).

POST /v2/donations/:id/send_receipt Resend receipt

Resend the donation receipt email to the donor.

Subscriptions

Subscriptions represent recurring donation schedules. Each subscription generates donations on its configured frequency.

GET /v2/subscriptions List subscriptions

Returns recurring subscriptions for the specified account.

Parameter	Description
account_id required	Account identifier
limit	Results per page (max 100)
offset	Pagination offset

GET /v2/subscriptions/:id Get subscription

Retrieve a single subscription by unique identifier.

POST /v2/subscriptions/:id Update subscription

Update a subscription's amount, frequency, or payment method.

POST /v2/subscriptions/:id/run_now Charge now

Immediately trigger a charge for a recurring subscription instead of waiting for the next scheduled date.

People

People represent donors and contacts in the system. A person is automatically created when a donation is made with a new email address.

GET /v2/people List people

Returns people (donors/contacts) for the specified account. Requires authentication.

Parameter	Description
account_id required	Account identifier
keyword optional	Search by name or email
limit	Results per page (max 100)
offset	Pagination offset

GET /v2/people/:id Get person

Retrieve a single person by unique identifier.

POST /v2/people Create person

Create a new person record. Can be used without authentication.

GET /v2/people/exists Check if person exists

Check if a person exists by email address. Public endpoint.

GET /v2/people/tax_receipt Get tax receipt

Generate a tax receipt for a donor for a given period.

Fundraisers

Fundraisers are individual or team-based sub-campaigns created by supporters for peer-to-peer fundraising.

GET /v2/fundraisers List fundraisers

Returns fundraisers for the specified account. Public fundraisers are accessible without authentication.

Parameter	Description
account_id required	Account identifier
campaign_id optional	Filter by parent campaign
limit	Results per page (max 100)
offset	Pagination offset

GET /v2/fundraisers/:id Get fundraiser

Retrieve a single fundraiser by unique identifier.

Forms

Forms define the configuration for embeddable donation forms, including presets, fields, styling, and payment options.

GET /v2/forms List forms

Returns forms for the specified account.

GET /v2/forms/:id Get form

Retrieve a single form by unique identifier.

GET /v2/forms/:id/config Get form config

Returns the full configuration for a form, including all options needed to render the embeddable donation form. Public endpoint.

POST /v2/forms Create form

Create a new donation form configuration.

POST /v2/forms/:id Update form

Update an existing form's configuration.

POST /v2/forms/:id/make_form_default Set as default

Set this form as the default form for the account.

DELETE /v2/forms/:id Delete form

Delete a form. This action cannot be undone.

Webhooks

Webhooks allow you to receive HTTP POST notifications when events occur in Donately (e.g., donation created, subscription cancelled).

GET /v2/webhooks List webhooks

Returns configured webhooks for the account.

GET /v2/webhooks/:id Get webhook

Retrieve a single webhook configuration.

POST /v2/webhooks Create webhook

Register a new webhook URL to receive event notifications.

DELETE /v2/webhooks/:id Delete webhook

Remove a webhook. You will no longer receive notifications at this URL.