POST /v1/forms/{formID}/links — create a prefilled checkout link

The Create Link endpoint produces a shareable URL that opens the form’s checkout with fields pre-populated. The donor data is stored server-side under a linkID — the URL itself is short and doesn’t expose the prefill values in query parameters. A link belongs to its parent form. Deactivating the form does not deactivate its links, but a link pointing at a deleted form will fail to load checkout.

Endpoint

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

Authentication

string

required

Bearer token using your API key. Format: Bearer cs_live_your_key

Path parameters

string

required

The unique identifier of the parent form. Returns 404 if the form doesn’t exist for your organization, 403 if it belongs to a different organization, 410 if it has been deleted.

Discovering what to prefill

Before building the request body, fetch the parent form and your organization config so you know which keys to set:

# Discover form-level custom inputs, funds, frequencies, tickets, productGroups
curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms/{formID} \
  -H "Authorization: Bearer cs_live_your_key"

# Discover organization-level globalCustomInputs and organizationBaseURLs (for overlay)
curl https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/organization \
  -H "Authorization: Bearer cs_live_your_key"

Both responses are cacheable per organization — fetch once at startup and reuse.

Request body

string

Internal label for the link, shown in the dashboard’s URL Builder list. Max 200 characters. Defaults to "API link — {timestamp}" if omitted.

string

Where the link should resolve. Optional — auto-derived from the form’s type if omitted.

HOSTED_PAGE_DONATE — fundraising/sponsorship/crowdfunding forms (default for non-EVENT)
HOSTED_PAGE_ATTEND — event forms (default for EVENT)
OVERLAY_DONATE — overlay snippet on your organization’s website (non-EVENT)
OVERLAY_ATTEND — overlay snippet on your organization’s website (EVENT)

Overlay destinations require organizationBaseURLs to be configured on your organization. Check via GET /v1/organization first; the API will return a 400 if it’s not set.

string

Required when destinationType is OVERLAY_DONATE or OVERLAY_ATTEND. URL path on your organization’s site where the overlay-trigger snippet lives, e.g. /give. Must begin with /.

object

Fields to pre-populate at checkout. All keys are optional. Unknown keys return a 400 with a list of accepted keys.

Prefill — donor identity

string

Donor’s first name.

string

Donor’s last name.

string

Donor’s email address.

string

Donor’s phone number. Format is not validated by the API — pass it as it should be displayed.

string

Donor’s organization or company name. Only shown if the form has enableOrganizationName enabled.

Prefill — address

string

Donor’s street address. Only shown if the form has enableBillingAddress enabled.

string

Apartment, suite, or unit number.

string

City.

string

State, province, or region.

string

Postal or ZIP code.

string

Country code or name. Only shown if the form has enableCountryDropdown enabled.

Prefill — donation amount

number

Donation amount. Must be between 0.01 and 1,000,000. Booleans are rejected. For sponsorship-style PRODUCT forms, set this to the chosen product’s price so the sponsorship UI renders as selected at checkout. For crowdfunding forms with giving levels, set this to the matching giving-level amount.

string

Fund to designate the gift to. Must match one of the form’s configured funds exactly (case-sensitive). Discoverable from GET /v1/forms/{id}’s funds array.

string

Donation cadence. One of ONE_TIME, DAILY, WEEKLY, MONTHLY, ANNUALLY. Must also be enabled on the form. Discoverable from GET /v1/forms/{id}’s frequencies array.

Prefill — custom inputs

object

Pre-populate the form’s customInputs and the organization’s globalCustomInputs. Object keys may be either the input’s id or its title (case-sensitive). Unknown keys return 400 with a list of valid IDs/titles.Form-level inputs are discoverable via GET /v1/forms/{id} (customInputs field). Organization-level globals via GET /v1/organization (globalCustomInputs field).

Prefill — sponsorship (PRODUCT forms only)

Available when the form’s formType is PRODUCT. Both keys are case-sensitive and must match values configured on the form (visible in the productGroups field of GET /v1/forms/{id}).

string

Name of the sponsorship group, e.g. "East". Must match a productGroups[].productGroupName on the form.

string

Name of the chosen product within the group, e.g. "New York". Must match a productName within the chosen sponsorshipGroup. Requires sponsorshipGroup to also be set.

Prefill — ticket (EVENT forms only)

Available when the form’s formType is EVENT.

string

Ticket name to pre-select, e.g. "General Admission". Must match a configured ticket on the event form. Tickets are stored on the event’s element record — fetch the form to see configured ticket names.

Prefill — attendees (EVENT forms only)

Available when the form’s formType is EVENT. Pre-populates the built-in First Name / Last Name / Email fields on the Attendee Info step. These are distinct from the donor identity fields above: the donor is the purchaser, attendees are the people the tickets are for.

object[]

Positional array of attendees. attendees[0] fills the first attendee, attendees[1] the second, and so on — matching the order seats are added at checkout. Every field in each entry is optional. Maximum 50 attendees.Each entry accepts:

firstName — attendee’s first name
lastName — attendee’s last name
email — attendee’s email

Only these built-in fields are supported. Attendee custom questions (e.g. Age, Gender) are not prefillable yet.

Pair attendees with ticket. Setting ticket pre-selects the event’s ticket so the buyer lands directly on a populated Attendee Info step — ideal for “register a known member” links where one attendee maps to one ticket.

Prefill — UTM parameters

string

UTM source (e.g. newsletter, facebook). Stored and recorded with the donation.

string

UTM medium (e.g. email, social).

string

UTM campaign (e.g. spring-2026).

string

UTM term.

string

UTM content.

Response

string

Unique identifier for the link. Use this with Get Link, Update Link, Delete Link, or the activate/deactivate endpoints.

string

The parent form’s ID, echoed from the path.

string

The shareable URL. Shape varies by destinationType:

HOSTED_PAGE_DONATE → https://charitystack.com/donate/{formID}?elementid={linkID}
HOSTED_PAGE_ATTEND → https://charitystack.com/attend/{formID}?elementid={linkID}
OVERLAY_* → {your-organization-base-url}{overlayPath}?donate&formid={formID}&elementid={linkID} (or ?attend for overlay attend)

string

The link’s internal label (either what you sent, or the default "API link — {timestamp}").

string

Echo of the destination type used (either supplied or auto-derived).

string

Echo of the overlay path; empty string for hosted-page destinations.

Status codes

Code	Description
`201`	Link created successfully.
`400`	Validation error — invalid JSON, unknown prefill key, bad type, amount out of range, unknown frequency, fund not configured on this form, sponsorship/ticket mismatch with form type, overlay missing `overlayPath`, or organization missing `organizationBaseURLs`.
`401`	Missing or invalid API key.
`403`	Form belongs to a different organization.
`404`	No form found with the given ID.
`410`	Form was found but has been deleted.
`500`	Internal error.

Examples

Basic prefilled donation link

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms/{formID}/links \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Outreach email — May 2026",
    "prefill": {
      "firstName": "Akif",
      "lastName": "Abidi",
      "email": "akif@example.org",
      "amount": 50,
      "frequency": "MONTHLY"
    }
  }'

With custom inputs (form-level + global)

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms/{formID}/links \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gala invite",
    "prefill": {
      "firstName": "Akif",
      "email": "akif@example.org",
      "amount": 100,
      "customInputs": {
        "T-shirt size": "M",
        "How did you hear about us?": "Friend"
      }
    }
  }'

Sponsorship (PRODUCT form)

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms/{formID}/links \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sponsor a city — NY",
    "prefill": {
      "firstName": "Akif",
      "email": "akif@example.org",
      "amount": 500,
      "sponsorshipGroup": "East",
      "sponsorshipItem": "New York"
    }
  }'

Event ticket prefill

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms/{formID}/links \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gala — VIP invite",
    "prefill": {
      "firstName": "Akif",
      "email": "akif@example.org",
      "amount": 250,
      "ticket": "General Admission"
    }
  }'

Event attendee prefill

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms/{formID}/links \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Member registration — Jane Doe",
    "prefill": {
      "ticket": "General Admission",
      "attendees": [
        { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.org" }
      ]
    }
  }'

Overlay destination on your own site

cURL

curl -X POST https://0k90mc4jjj.execute-api.us-east-2.amazonaws.com/v1/forms/{formID}/links \
  -H "Authorization: Bearer cs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Site banner CTA",
    "destinationType": "OVERLAY_DONATE",
    "overlayPath": "/give",
    "prefill": {
      "fund": "General Fund",
      "amount": 100,
      "utmSource": "homepage-banner"
    }
  }'

201 response

{
  "linkID": "bc033789-1ee2-4f3f-bec5-2f108c2d65ba",
  "formID": "550e8400-e29b-41d4-a716-446655440000",
  "checkoutUrl": "https://your-site.org/give?donate&formid=550e8400-e29b-41d4-a716-446655440000&elementid=bc033789-1ee2-4f3f-bec5-2f108c2d65ba",
  "name": "Site banner CTA",
  "destinationType": "OVERLAY_DONATE",
  "overlayPath": "/give"
}

Validation error responses

{
  "error": "prefill.frequency 'QUARTERLY' is not enabled on this form (enabled: ['ONE_TIME', 'MONTHLY'])"
}

{
  "error": "prefill.customInputs['shirtsize'] does not match any customInput on this form or globalCustomInput on the organization. Known IDs/titles: ['T-shirt size', 'tshirt-id-123', 'How did you hear about us?']"
}

{
  "error": "prefill.sponsorshipGroup 'NonExistent' is not a productGroup on this form (available: ['East', 'Northwest'])"
}

{
  "error": "Overlay destinations require organizationBaseURLs to be configured on the organization. Configure your website URL in Settings → Organization in the dashboard first."
}

Organization

Payments

Subscriptions

Contacts

Forms

Prefilled-Checkout Links

Webhooks

Analytics

POST /v1/forms/{formID}/links — create a prefilled checkout link

Endpoint

Authentication

Path parameters

Discovering what to prefill

Request body

Prefill — donor identity

Prefill — address

Prefill — donation amount

Prefill — custom inputs

Prefill — sponsorship (PRODUCT forms only)

Prefill — ticket (EVENT forms only)

Prefill — attendees (EVENT forms only)

Prefill — UTM parameters

Response

Status codes

Examples

Basic prefilled donation link

With custom inputs (form-level + global)

Sponsorship (PRODUCT form)

Event ticket prefill

Event attendee prefill

Overlay destination on your own site

Validation error responses

​Endpoint

​Authentication

​Path parameters

​Discovering what to prefill

​Request body

​Prefill — donor identity

​Prefill — address

​Prefill — donation amount

​Prefill — custom inputs

​Prefill — sponsorship (PRODUCT forms only)

​Prefill — ticket (EVENT forms only)

​Prefill — attendees (EVENT forms only)

​Prefill — UTM parameters

​Response

​Status codes

​Examples

​Basic prefilled donation link

​With custom inputs (form-level + global)

​Sponsorship (PRODUCT form)

​Event ticket prefill

​Event attendee prefill

​Overlay destination on your own site

​Validation error responses

Endpoint

Authentication

Path parameters

Discovering what to prefill

Request body

Prefill — donor identity

Prefill — address

Prefill — donation amount

Prefill — custom inputs

Prefill — sponsorship (PRODUCT forms only)

Prefill — ticket (EVENT forms only)

Prefill — attendees (EVENT forms only)

Prefill — UTM parameters

Response

Status codes

Examples

Basic prefilled donation link

With custom inputs (form-level + global)

Sponsorship (PRODUCT form)

Event ticket prefill

Event attendee prefill

Overlay destination on your own site

Validation error responses