POST /v1/forms — create a donation form

The Create Form endpoint builds a new donation form and returns its hosted URL and embed snippet. Only title and funds are required — all other fields have sensible defaults. The form is immediately live at charitystack.com/donate/{formID} unless you set active to false.

Endpoint

POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms

Authentication

string

required

Bearer token using your API key. Format: Bearer cs_live_your_key

Request body

Required fields

string

required

Display name for the form. Must be unique within your account.

string[]

required

List of fund names donors can designate their gift to. At least one required.

Form type

string

default:"fundraising"

fundraising or event. Event forms require at least one ticket.

string

default:"standard"

For fundraising forms only. Controls how amounts are presented:

standard — Free-form amounts with suggested values
giving_level — Named tiers (requires givingLevels array)
sponsorship — Grouped packages (requires sponsorshipGroups array)

The formType and amountType you send are mapped to an internal value in the response. See Form type mapping for details.

Frequencies & amounts

string[]

Donation frequencies to enable. Values: ONE_TIME, DAILY, WEEKLY, MONTHLY, ANNUALLY. Required for fundraising forms. Event forms default to ["ONE_TIME"].

string

Pre-selected frequency when the form loads. Defaults to the first item in frequencies.

number[]

default:"[25, 50, 100, 250, 500]"

Suggested one-time amounts. Each must be between

1 and

1,000,000.

number[]

default:"[10, 25, 50, 100]"

Suggested monthly amounts.

Giving levels

object[]

Named donation tiers. Required when amountType is giving_level.Each object requires title (string), amount (number, > 0), and description (string).

Sponsorship groups

object[]

Sponsorship packages. Required when amountType is sponsorship. Each group must have at least one option.Each group: groupTitle (string), description (string), options array of { optionTitle, amount }.

Appearance

string

default:"#3B82F6"

Hex color for form styling. Must be valid format: #XXXXXX.

string

Supporting text shown below the title. Maximum 650 characters.

boolean

default:"true"

Set to false to create the form in a draft state.

Donor options

Fundraising features

Event fields

boolean

default:"false"

Display event date, time, and location. When true, eventDate and startTime become required.

Tickets (event forms)

object[]

Event tickets. Required for event forms — at least one ticket must be provided.Each ticket requires:

name (string) — must be unique across all tickets
price (number) — must be >= 0 (free tickets allowed)
quantity (integer) — must be > 0
ticketType (string) — INDIVIDUAL or GROUP
groupSize (integer) — required for GROUP tickets, must be > 1

Discount codes for tickets. Each requires code, discountType (percentage or amount), discountValue, quantity, and applicableTickets (array of ticket names).

Custom email

boolean

default:"false"

Enable custom receipt emails. When true, replyToAddress, emailSubject, and customMessage are all required.

Custom inputs & FAQs

object[]

Additional form fields. Each requires question, inputType (short_text, long_text, single_select, multi_select), and required (boolean). Dropdown types (single_select, multi_select) require an options array with at least 2 items.

object[]

FAQ items displayed on the form. Each requires question and answer.

Response

Status codes

Code	Description
`201`	Form created successfully.
`400`	Validation error. Response includes `error` (single issue) or `error` + `details` array (multiple issues).
`401`	Missing or invalid API key.
`409`	A form with this title already exists for your account.

Examples

Fundraising form

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Annual Giving Campaign 2025",
    "funds": ["General Fund", "Education Program"],
    "frequencies": ["ONE_TIME", "MONTHLY"],
    "formType": "fundraising",
    "amountType": "standard",
    "description": "Support our mission with a tax-deductible donation.",
    "color": "#2563EB",
    "enableFundraisingBar": true,
    "goal": 50000,
    "oneTimeAmounts": [25, 50, 100, 250, 500],
    "monthlyAmounts": [10, 25, 50, 100]
  }'

Event form

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Annual Gala 2025",
    "funds": ["Event Fund"],
    "formType": "event",
    "description": "Join us for an evening of celebration.",
    "color": "#7C3AED",
    "enableTimeAndLocation": true,
    "eventDate": "2025-06-15",
    "startTime": "18:00",
    "endTime": "22:00",
    "location": "Grand Ballroom, 123 Main St",
    "tickets": [
      {
        "name": "Individual Ticket",
        "price": 150,
        "quantity": 200,
        "ticketType": "INDIVIDUAL"
      },
      {
        "name": "Table of 8",
        "price": 1000,
        "quantity": 20,
        "ticketType": "GROUP",
        "groupSize": 8
      }
    ]
  }'

201 response

{
  "formID": "550e8400-e29b-41d4-a716-446655440000",
  "formUrl": "https://charitystack.com/donate/550e8400-e29b-41d4-a716-446655440000",
  "embedHTML": "<iframe src=\"https://charitystack.com/donate/550e8400-e29b-41d4-a716-446655440000\" width=\"100%\" height=\"800\" frameborder=\"0\" style=\"border: none;\"></iframe>",
  "message": "Form created successfully"
}

400 response (validation errors)

{
  "error": "Validation failed",
  "details": [
    "title is required",
    "funds is required (array of fund names)",
    "frequencies is required for fundraising forms"
  ]
}

Organization

Payments

Subscriptions

Contacts

Forms

Prefilled-Checkout Links

Webhooks

Analytics

POST /v1/forms — create a donation form

Endpoint

Authentication

Request body

Required fields

Form type

Frequencies & amounts

Giving levels

Sponsorship groups

Appearance

Donor options

Fundraising features

Event fields

Tickets (event forms)

Custom email

Custom inputs & FAQs

Response

Status codes

Examples

Fundraising form

Event form

​Endpoint

​Authentication

​Request body

​Required fields

​Form type

​Frequencies & amounts

​Giving levels

​Sponsorship groups

​Appearance

​Donor options

​Fundraising features

​Event fields

​Tickets (event forms)

​Promo codes (event forms)

​Custom email

​Custom inputs & FAQs

​Response

​Status codes

​Examples

​Fundraising form

​Event form

Endpoint

Authentication

Request body

Required fields

Form type

Frequencies & amounts

Giving levels

Sponsorship groups

Appearance

Donor options

Fundraising features

Event fields

Tickets (event forms)

Promo codes (event forms)

Custom email

Custom inputs & FAQs

Response

Status codes

Examples

Fundraising form

Event form