Building donation forms with the CharityStack API

CharityStack forms are embeddable donation experiences hosted at charitystack.com/donate/{formID}. You can share the link directly, embed the form on your website, or use it as the checkout flow for a fundraising campaign or ticketed event. The forms API lets you create and manage these forms programmatically — useful for organizations that run many campaigns, need to automate form setup, or want to integrate form creation into a broader CRM or event management workflow.

The form object

The list endpoint (GET /v1/forms) returns a summary of each form. Use GET /v1/forms/{id} to retrieve the full configuration.

Summary fields (list endpoint)

Field	Type	Description
`formID`	string	Unique identifier for the form
`formUrl`	string	Live URL where donors can access the form (`charitystack.com/donate/{formID}`)
`title`	string	Display name shown at the top of the form
`description`	string	Supporting text shown below the title
`formType`	string	Internal form type (see mapping below)
`funds`	array[string]	List of fund names donors can designate their gift to
`frequencies`	array[string]	Donation frequencies available on the form
`color`	string	Hex color used for form styling
`headerImage`	string	URL to the form’s header image
`active`	boolean	Whether the form is currently accepting donations
`goal`	number	Fundraising goal amount (when fundraising bar is enabled)
`eventDate`	string	Event date (event forms only)
`startTime`	string	Event start time (event forms only)
`endTime`	string	Event end time (event forms only)
`location`	string	Event location (event forms only)

Full form object (get-by-id endpoint)

The GET /v1/forms/{id} response includes all summary fields plus the complete configuration: amount arrays, default amounts, giving levels, sponsorship groups, tickets, promo codes, custom inputs, FAQs, all enable toggles, custom email settings, and event details. See the Get Form endpoint reference for the full schema.

Form types

CharityStack supports two top-level form categories, with additional sub-types for fundraising forms.

Fundraising forms

Standard donation forms used for general fundraising campaigns. Supports three amount presentation styles:

standard — Free-form amount entry with suggested amounts
giving_level — Named tiers (e.g., Bronze, Silver, Gold donor)
sponsorship — Grouped sponsorship packages with fixed prices

Event forms

Ticketed event registration forms. Supports ticket types (individual and group), promo codes, and event date/time/location details. At least one ticket is required.

Form type mapping

When you create a form, you pass a friendly formType and amountType. The API stores and returns a legacy internal value:

Create input (`formType`)	Create input (`amountType`)	Response value (`formType`)
`fundraising`	`standard`	`EMBED_FORM`
`fundraising`	`giving_level`	`CROWDFUNDING_FORM`
`fundraising`	`sponsorship`	`PRODUCT`
`event`	(ignored)	`EVENT`

The response values (EMBED_FORM, CROWDFUNDING_FORM, PRODUCT) are legacy internal names. This naming mismatch is expected — the create endpoint accepts the friendly names, and the GET endpoints return the stored database values.

Key features

Forms support a rich set of optional features you can enable when creating or updating a form.

Feature	Description
Giving levels	Named donation tiers with fixed amounts and benefit descriptions
Sponsorship groups	Grouped packages for corporate or major donors
Event tickets	Individual and group ticket types with optional quantity limits
Promo codes	Percentage or fixed-amount discount codes tied to specific tickets
Custom inputs	Additional form fields (short text, long text, dropdowns, multi-select)
FAQs	Accordion-style FAQ section displayed on the form
Fundraising bar	Progress bar toward a stated goal amount
Donor contact list	Display of supporters on the form page

Creating a form

When you call POST /v1/forms, two fields are always required. All other fields are optional and fall back to sensible defaults.

Field	Required	Default	Notes
`title`	Yes	—	Displayed at the top of the form
`funds`	Yes	—	At least one fund name is required
`formType`	No	`fundraising`	Use `event` for ticketed event forms
`amountType`	No	`standard`	For fundraising: `standard`, `giving_level`, or `sponsorship`
`frequencies`	Conditional	`["ONE_TIME"]`	Required for fundraising forms; defaults to `ONE_TIME` for event forms
`color`	No	`#3B82F6`	Must be valid hex format (`#XXXXXX`)
`active`	No	`true`	Set to `false` to create the form in a draft state

Conditional requirements

When enableFundraisingBar is true, you must also provide a goal value greater than zero.
When enableCustomEmail is true, the fields replyToAddress, emailSubject, and customMessage are all required.
When enableTimeAndLocation is true, eventDate and startTime are required. endTime, location, eventDetails, and timeZone are optional.
When amountType is giving_level, you must provide at least one item in givingLevels.
When amountType is sponsorship, you must provide at least one group in sponsorshipGroups with at least one option.
Event forms require at least one ticket in the tickets array.

Validation rules

Amount values (oneTimeAmounts, monthlyAmounts, etc.) must be between

1 and

1,000,000. Descriptions are limited to 650 characters. Dropdown-type custom inputs (single_select, multi_select) require at least 2 options. Ticket names must be unique within a form, and GROUP tickets require a groupSize greater than 1.

Example: create a basic fundraising form

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms \
  -H "Authorization: Bearer cs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Annual Fund 2025",
    "funds": ["General Fund", "Education Fund"],
    "frequencies": ["ONE_TIME", "MONTHLY"],
    "color": "#10B981"
  }'

A successful response includes the new form’s ID, its live URL, and an embed snippet:

{
  "formID": "form_abc123",
  "formUrl": "https://charitystack.com/donate/form_abc123",
  "embedHTML": "<iframe src=\"...\"></iframe>",
  "message": "Form created successfully"
}

API endpoints

Create a form

Create a new fundraising or event form with full configuration options.

List forms

Retrieve all forms for your account with pagination support.

Get a form

Retrieve the full configuration for a single form by ID.

Update a form

Update an existing form’s configuration. Partial updates supported.

Delete a form

Soft-delete a form. Returns 410 Gone on subsequent access.

Get Started

Core Concepts

Guides

Building donation forms with the CharityStack API

The form object

Summary fields (list endpoint)

Full form object (get-by-id endpoint)

Form types

Fundraising forms

Event forms

Form type mapping

Key features

Creating a form

Conditional requirements

Validation rules

Example: create a basic fundraising form

API endpoints

Create a form

List forms

Get a form

Update a form

Delete a form

​The form object

​Summary fields (list endpoint)

​Full form object (get-by-id endpoint)

​Form types

Fundraising forms

Event forms

​Form type mapping

​Key features

​Creating a form

​Conditional requirements

​Validation rules

​Example: create a basic fundraising form

​API endpoints

Create a form

List forms

Get a form

Update a form

Delete a form

The form object

Summary fields (list endpoint)

Full form object (get-by-id endpoint)

Form types

Form type mapping

Key features

Creating a form

Conditional requirements

Validation rules

Example: create a basic fundraising form

API endpoints