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"
}

{
  "success": true,
  "data": [ ... ],
  "count": 142,
  "offset": 0,
  "per_page": 20
}

v2019-03-15 uses a flat response structure. Upgrade to v2022-12-15 for standardized summary and params objects.

Errors

Error responses follow a consistent format:

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

{
  "success": false,
  "error": "Description of what went wrong"
}

v2019-03-15 returns a simpler error format. Upgrade to v2022-12-15 for structured type, code, and request_id fields.

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.

Response

{
  "object": "account",
  "id": "act_ba7d12ab27bb",
  "title": "My Nonprofit",
  "currency": "usd",
  "integration_accounts": [ ... ],
  "partner_type": "standard",
  "page_template": { ... },
  "billing": {
    "plan": "grow",
    "subscription_stripe_id": "sub_xxx",
    "subscription_prepaid_max_usd": 50000,
    "subscription_status": "active"
  },
  "created_at": "2020-01-15T12:00:00Z",
  "updated_at": "2026-02-10T08:30:00Z",
  "request_id": "req_1234567890123"
}

{
  "success": true,
  "data": {
    "id": "act_ba7d12ab27bb",
    "title": "My Nonprofit",
    "currency": "usd",
    "billing": {
      "plan": "grow"
    },
    "google_analytics_id": "UA-12345678-1",
    "created_at": "2020-01-15T12:00:00Z",
    "updated_at": "2026-02-10T08:30:00Z"
  }
}

v2019-03-15 hides integration_accounts, partner_type, page_template, and billing subscription details. It adds a computed google_analytics_id field.

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.

Response

{
  "object": "campaign",
  "id": "cmp_1a2b3c4d5e6f",
  "title": "Annual Fund Drive",
  "status": "published",
  "type": "donation",
  "goal_in_cents": 10000000,
  "total_raised_in_cents": 4250000,
  "page_template": { ... },
  "created_at": "2026-01-01T00:00:00Z",
  "request_id": "req_1234567890123"
}

{
  "success": true,
  "data": {
    "id": "cmp_1a2b3c4d5e6f",
    "title": "Annual Fund Drive",
    "status": "published",
    "type": "donation",
    "goal_in_cents": 10000000,
    "total_raised_in_cents": 4250000,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

v2019-03-15 hides the page_template field.

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.

Response

{
  "object": "donation",
  "id": "dnt_9f8e7d6c5b4a",
  "amount_in_cents": 5000,
  "currency": "usd",
  "status": "completed",
  "campaign_id": "cmp_1a2b3c4d5e6f",
  "person_id": "per_a1b2c3d4e5f6",
  "recurring": false,
  "anonymous": false,
  "comment": "Keep up the great work!",
  "on_behalf_of": null,
  "donation_type": "card",
  "ecard": { ... },
  "origin": "form",
  "notes": "Internal note",
  "payment_intent_secret": "pi_xxx_secret_yyy",
  "paypal_order_id": null,
  "subscription": {
    "id": "sub_xxx",
    "recurring_start_day": 1,
    "recurring_stop_day": null,
    "recurring_frequency": "monthly"
  },
  "fundraiser": {
    "id": "fun_xxx",
    "type": "individual"
  },
  "form": { "id": "frm_xxx", "title": "Main Form" },
  "created_at": "2026-03-01T14:30:00Z",
  "updated_at": "2026-03-01T14:30:00Z",
  "request_id": "req_1234567890123"
}

{
  "success": true,
  "data": {
    "id": "dnt_9f8e7d6c5b4a",
    "amount_in_cents": 5000,
    "currency": "usd",
    "status": "completed",
    "campaign_id": "cmp_1a2b3c4d5e6f",
    "person_id": "per_a1b2c3d4e5f6",
    "recurring": false,
    "anonymous": false,
    "comment": "Keep up the great work!",
    "on_behalf_of": null,
    "donation_type": "cc",
    "subscription": {
      "id": "sub_xxx"
    },
    "fundraiser": {
      "id": "fun_xxx"
    },
    "created_at": "2026-03-01T14:30:00Z",
    "updated_at": "2026-03-01T14:30:00Z"
  }
}

v2019-03-15 hides ecard, origin, notes. Nested subscription removes recurring_start_day, recurring_stop_day, recurring_frequency. Nested fundraiser removes type. Donation types limited to cc, ach, cash, paypal.

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)

Additional v2022-12-15 Parameters

Parameter	Description
donation_type optional	`card`, `stripe`, `ach`, `paypal`, `cash`, `dipjar`
origin optional	Source of the donation (e.g. `form`, `api`, `dashboard`)
notes optional	Internal notes (not visible to donor)
ecard optional	E-card configuration object

Accepted donation_type values: cc, ach, cash, paypal

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.

Response

{
  "object": "subscription",
  "id": "sub_4a3b2c1d0e9f",
  "amount_in_cents": 2500,
  "currency": "usd",
  "frequency": "monthly",
  "status": "active",
  "person_id": "per_a1b2c3d4e5f6",
  "campaign_id": "cmp_1a2b3c4d5e6f",
  "donations_count": 12,
  "next_charge_at": "2026-04-01T00:00:00Z",
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2026-03-01T00:00:00Z",
  "request_id": "req_1234567890123"
}

{
  "success": true,
  "data": {
    "id": "sub_4a3b2c1d0e9f",
    "amount_in_cents": 2500,
    "currency": "usd",
    "frequency": "monthly",
    "status": "active",
    "person_id": "per_a1b2c3d4e5f6",
    "campaign_id": "cmp_1a2b3c4d5e6f",
    "next_charge_at": "2026-04-01T00:00:00Z",
    "created_at": "2025-06-15T10:00:00Z",
    "updated_at": "2026-03-01T00:00:00Z"
  }
}

v2019-03-15 hides the donations_count field.

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.

Response

{
  "object": "fundraiser",
  "id": "fun_7e8f9a0b1c2d",
  "title": "Jane's Run for Hope",
  "type": "individual",
  "parent": { "id": "fun_xxx", "title": "Team Alpha" },
  "team_leader": { "id": "per_xxx", "name": "Jane Doe" },
  "page_template": { ... },
  "goal_in_cents": 500000,
  "total_raised_in_cents": 125000,
  "campaign_id": "cmp_1a2b3c4d5e6f",
  "created_at": "2026-02-01T00:00:00Z",
  "request_id": "req_1234567890123"
}

{
  "success": true,
  "data": {
    "id": "fun_7e8f9a0b1c2d",
    "title": "Jane's Run for Hope",
    "goal_in_cents": 500000,
    "total_raised_in_cents": 125000,
    "campaign_id": "cmp_1a2b3c4d5e6f",
    "created_at": "2026-02-01T00:00:00Z"
  }
}

v2019-03-15 hides type, parent, team_leader, and page_template fields.

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.

Response

{
  "object": "form",
  "id": "frm_3d4e5f6a7b8c",
  "title": "Main Donation Form",
  "url": "https://donately.com/form/xxx",
  "form_editor": { ... },
  "page_template": { ... },
  "account_id": "act_ba7d12ab27bb",
  "created_at": "2025-09-01T00:00:00Z",
  "request_id": "req_1234567890123"
}

{
  "success": true,
  "data": {
    "id": "frm_3d4e5f6a7b8c",
    "title": "Main Donation Form",
    "account_id": "act_ba7d12ab27bb",
    "created_at": "2025-09-01T00:00:00Z"
  }
}

v2019-03-15 hides url, form_editor, and page_template fields.

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.