Donation Forms

Donation Forms are the most distinctive concept in the Raise product: branded, configurable forms that donors fill out to give. They live under Campaigns and Segments, capture the donor’s information, designate the gift to one or more Projects, and submit through POST /api/Raise/give. For partner integrations, the API surface for Donation Forms is narrower than the product’s UI surface. Most form configuration happens in the Raise admin UI, not via the API. This page covers what the API does expose, what it doesn’t, and the integration patterns that work given these constraints.

Donation Form configuration is not available through the current Raise API. There is no top-level /api/Form or /api/Page resource for creating, updating, or listing forms. Form configuration — fields, designations, styling, embed settings — happens exclusively in the Raise admin UI.What the API does expose: form context embedded in Gift records (so partners can see which form produced a given gift), a generate-page endpoint that creates personalized donor-specific pages, and a per-Segment page-count metric. Future API versions are expected to add direct form-management endpoints.

How forms fit in the data model

Forms sit between Campaigns and the gifts they produce. The hierarchy: A Campaign can have multiple Segments. Each Segment can have multiple Forms. Each Form produces Gifts that carry the form’s identifier in their record. This lets the customer’s team trace any Gift back to:

The specific form the donor filled out
The segment that segment-routed the donor (email, social, direct mail, etc.)
The campaign the segment belongs to

For partner integrations doing donation analytics, the chain of identifiers on a Gift (form.id, segment, campaignName) is the foundation of channel-attribution reporting.

What the API exposes about forms

Three things:

1. Form attribution on Gift records

Every Gift has a form field carrying a GiftFormModel:

Field	Type	Description
`id`	integer	The form’s ID. Stable identifier you can use to group gifts by source form.
`title`	string	The form’s display title.
`landingUrl`	string	The URL the donor landed on to start the donation flow.
`referringUrl`	string	The URL the donor came from (the `Referer` header at the start of the donation flow).
`isLegacy`	boolean	`true` if the form is a legacy form built on an older form engine. Useful for partners that need to distinguish modern forms from older ones.

That’s the full set of form fields available in the API. Form configuration — field labels, validation rules, designation defaults, styling — isn’t exposed. Example: reading the form context off a Gift:

JavaScript

const gift = await fetch(
  `https://prod-api.raisedonors.com/api/Gift/${giftId}`,
  { headers: { Authorization: `Bearer ${process.env.RAISE_API_TOKEN}` } }
).then((r) => r.json());

console.log('Form attribution:', {
  formId: gift.form?.id,
  formTitle: gift.form?.title,
  landingUrl: gift.form?.landingUrl,
  referringUrl: gift.form?.referringUrl,
  segment: gift.segment,
  campaign: gift.campaignName,
});

2. Personalized page generation for a donor

POST /api/Donor/{donorId}/generate-page generates a hosted donation page personalized to a specific donor — pre-filling the donor’s identity so they need only choose the amount and complete payment:

cURL

curl -X POST https://prod-api.raisedonors.com/api/Donor/12345/generate-page \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

The most common use is renewal and major-donor cultivation campaigns — your integration sends a personalized URL in an email or text, and the donor only needs to confirm the amount and pay.

The request body schema for POST /api/Donor/{donorId}/generate-page is not detailed in the spec (the body schema is empty). The endpoint likely accepts parameters like campaignId or formId to identify which form to personalize, but the exact contract needs confirmation against the live API before partners can rely on specific request fields. Confirm with the platform team before building automation around this endpoint.

3. Page count per Segment

GET /api/Segment/{segmentId}/page-count returns the number of donation pages (forms) associated with a Segment:

cURL

curl https://prod-api.raisedonors.com/api/Segment/678/page-count \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Useful for the customer’s UI when displaying segment-level metrics (“This segment has 4 active donation forms”) without needing to list the forms themselves.

What the API doesn’t expose

The current spec doesn’t include:

Capability	Status
Create a new form via API	Not exposed
Update a form’s fields or configuration	Not exposed
List all forms for an organization	Not exposed
Get a form’s complete schema (fields, validators, defaults)	Not exposed
Publish or unpublish a form	Not exposed
Embed configuration (iframe code, embed scripts)	Not exposed
Form-level analytics (views, conversion rate, abandonment)	Not exposed directly — derive from Gift queries instead

Partner integrations that need any of these capabilities must coordinate through the customer’s Raise admin team and the admin UI. This is a documented constraint of the current API, not a workaround partners can avoid through clever pattern use.

Integration patterns that work today

Despite the narrow API surface, three patterns work well for partner integrations:

Pattern 1: form-aware gift analytics

For analytics integrations, the form.id plus the existing UTM and Campaign attribution fields on a Gift are enough to build per-form, per-channel, per-campaign performance dashboards.

JavaScript

// Group recent gifts by form
async function giftsByForm(sinceDate) {
  const gifts = await listAllGifts(sinceDate);
  const groups = new Map();

  for (const gift of gifts) {
    const formId = gift.form?.id ?? 'no-form';
    if (!groups.has(formId)) {
      groups.set(formId, {
        formTitle: gift.form?.title,
        count: 0,
        totalAmount: 0,
      });
    }
    const group = groups.get(formId);
    group.count++;
    group.totalAmount += gift.amount;
  }

  return groups;
}

The customer’s analytics team can use this to identify the top-performing forms, optimize underperforming ones, and report on per-form revenue.

Pattern 2: personalized donor pages in stewardship workflows

For donor stewardship and renewal campaigns, the generate-page endpoint creates personalized URLs that boost conversion compared to generic form links:

JavaScript

async function sendRenewalEmail(donor) {
  // Generate the personalized URL
  const pageResponse = await fetch(
    `https://prod-api.raisedonors.com/api/Donor/${donor.id}/generate-page`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.RAISE_API_TOKEN}`,
        'Content-Type': 'application/json',
      },
    }
  );
  const { pageUrl } = await pageResponse.json();

  // Send the email with the personalized URL
  await emailService.send({
    to: donor.email,
    subject: 'Renew your support',
    body: renewalTemplate({ donor, pageUrl }),
  });
}

Pattern 3: embedding forms via the admin UI’s embed code

For integrations that need to display a Raise donation form on a partner-hosted page, the embedding mechanism is the iframe or script tag the customer copies from the Raise admin UI. Your integration doesn’t need to call the API to embed the form — it embeds the form’s HTML output directly. This means the integration’s responsibility is:

Get the embed code from the customer (typically pasted into a settings field in your integration’s UI).
Include that code on the page where the form should appear.
Subscribe to webhook events to learn when gifts are completed.

The form itself handles payment processing, donor capture, and gift creation — all through the same POST /api/Raise/give path your integration would call if it embedded a fully custom form.

When form-management endpoints become available

The platform team is aware that the current Form API surface is narrower than what partners want. Future API versions are expected to add at least:

A form list endpoint (GET /api/Form/list or similar) for inventorying configured forms
A form get-by-ID endpoint for retrieving form schemas
Form-level metrics endpoints

When those are released, the documentation will be updated. For now, partner integration designs should treat form configuration as the customer’s admin-team domain and design around the form attribution data that’s available on Gifts.

Where to go next

Campaigns

The Campaign resource that owns Segments and the Forms beneath them.

Gifts

The Gift resource where form attribution data lives.

Embed a Form on a Website

The end-to-end recipe for getting a Raise form onto a customer’s site.

Process a Donation

What happens when a donor submits a form — the POST /api/Raise/give flow.

Getting Started

Core Concepts

Workflows

Webhooks

Recipes

Best Practices

How forms fit in the data model

What the API exposes about forms

1. Form attribution on Gift records

2. Personalized page generation for a donor

3. Page count per Segment

What the API doesn’t expose

Integration patterns that work today

Pattern 1: form-aware gift analytics

Pattern 2: personalized donor pages in stewardship workflows

Pattern 3: embedding forms via the admin UI’s embed code

When form-management endpoints become available

Where to go next

Campaigns

Gifts

Embed a Form on a Website

Process a Donation

​How forms fit in the data model

​What the API exposes about forms

​1. Form attribution on Gift records

​2. Personalized page generation for a donor

​3. Page count per Segment

​What the API doesn’t expose

​Integration patterns that work today

​Pattern 1: form-aware gift analytics

​Pattern 2: personalized donor pages in stewardship workflows

​Pattern 3: embedding forms via the admin UI’s embed code

​When form-management endpoints become available

​Where to go next

Campaigns

Gifts

Embed a Form on a Website

Process a Donation

How forms fit in the data model

What the API exposes about forms

1. Form attribution on Gift records

2. Personalized page generation for a donor

3. Page count per Segment

What the API doesn’t expose

Integration patterns that work today

Pattern 1: form-aware gift analytics

Pattern 2: personalized donor pages in stewardship workflows

Pattern 3: embedding forms via the admin UI’s embed code

When form-management endpoints become available

Where to go next