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

Authorization

string

required

Bearer token using your API key. Format: Bearer cs_live_your_key

Path parameters

formID

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

name

string

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

destinationType

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.

overlayPath

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 /.

prefill

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

prefill.firstName

string

Donor’s first name.

prefill.lastName

string

Donor’s last name.

prefill.email

string

Donor’s email address.

prefill.phone

string

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

prefill.organizationName

string

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

Prefill — address

prefill.address

string

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

prefill.address2

string

Apartment, suite, or unit number.

prefill.city

string

City.

prefill.state

string

State, province, or region.

prefill.zip

string

Postal or ZIP code.

prefill.country

string

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

Prefill — donation amount

prefill.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.

prefill.fund

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.

prefill.frequency

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

prefill.customInputs

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}).

prefill.sponsorshipGroup

string

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

prefill.sponsorshipItem

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.

prefill.ticket

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 — UTM parameters

prefill.utmSource

string

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

prefill.utmMedium

string

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

prefill.utmCampaign

string

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

prefill.utmTerm

string

UTM term.

prefill.utmContent

string

UTM content.

Response

linkID

string

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

formID

string

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

checkoutUrl

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)

name

string

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

destinationType

string

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

overlayPath

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

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

​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 — UTM parameters

​Response

​Status codes

​Examples

​Basic prefilled donation link

​With custom inputs (form-level + global)

​Sponsorship (PRODUCT form)

​Event ticket 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 — UTM parameters

Response

Status codes

Examples

Basic prefilled donation link

With custom inputs (form-level + global)

Sponsorship (PRODUCT form)

Event ticket prefill

Overlay destination on your own site

Validation error responses