Apply2Volunteer

Discard the open draft of a form that belongs to the authenticated organization. Requires an org API key or OAuth sign-in with the forms:write scope. Same checks as POST /api/v1/forms/{id}/discard. An open draft is an unpublished version newer than the published snapshot. This deletes that draft and clears drafted public settings. The published form stays. Returns { ok: true }. A form with no open draft returns 404 { error: "not found", message: "No open draft to discard." }. That includes a form that was never published and a published form with nothing left to discard. If the form changed since this discard was read, it writes nothing and returns 409 'This form changed. Reload and try again.' This does not delete the form. A form that belongs to another organization is not found.

Publish a draft form that belongs to the authenticated organization. Requires an org API key or OAuth sign-in with the forms:write scope. Runs the same checks as POST /api/v1/forms/{id}/publish, including field identity and stage validation. A form with no fields is rejected (400 'A form must have at least one field to publish.'). Publish returns 409 'Publish would remove a field that already has answers or consents.' when the draft would drop a field key that already has answers or consents on any version of the form. Returns formId, status published, publicUrl (the public form URL, the same value as publicFormUrl), the embed URL, and the embed snippet. Does not publish a form that belongs to another organization.

Save an unexpired anonymous preview into the authenticated organization as a draft. Requires an org API key or OAuth sign-in with the forms:write scope. Same save as POST /api/v1/tools/previews/{id}/claim. previewId is the token in previewUrl (/tools/p/{previewId}). Returns formId and editorUrl (/app/forms/{formId}). An unknown or expired preview is an error. A preview already saved by another organization is refused. Claiming the same preview again for this organization returns the same draft.

Convert a PDF URL into a stored preview for the authenticated organization. Requires an org API key with the forms:read scope. Returns the preview id and expiry. For a preview without a key, use preview_volunteer_form.

Create a blank draft form in the authenticated organization. Requires an org API key or OAuth sign-in with the forms:write scope. Same blank form as POST /api/v1/forms when no conversion, report, or preview is sent: title Volunteer application unless title is set, with First name and Email. Optional template volunteer-application-form or volunteer-interest-form seeds that template's fields instead, using the on-server parser. Workers AI stays off. An unknown template is an error and does not create a form. Title is at most 200 characters. MCP, an org API key, and OAuth share a limit of 60 creates per organization per hour. A website session is not counted. Returns formId and editorUrl (/app/forms/{formId}). Does not publish the form.

Fetch a PDF or page URL and save a draft form in the authenticated organization, the same way claiming a preview does. Requires an org API key with the forms:write scope. Uses the on-server parser only: Workers AI and other models stay off. Returns formId and editorUrl (/app/forms/{formId}). Does not publish the form. File contents are not logged.

Grade a blank volunteer form from pasted text or a document URL. No API key. Send a url or text, not both. Uses the on-server grader only: Workers AI and other models stay off. Returns score, letter grade, fixes (the top recommendations), and reportUrl (/tools/r/{id}) for the public share page when one is stored. Restricted fields such as Social Security numbers are left out of parsed; the score still counts them. Anonymous use shares the Form Grader limit of 5 per network per day and counts toward the daily anonymous MCP cap. An organization hourly limit applies when an org API key with the forms:read scope is sent. Does not grade a saved form.

Convert a blank volunteer application into an online form preview. No account and no API key. Send exactly one of a PDF or page url, pasted form text, or template (volunteer-application-form or volunteer-interest-form). Uses the on-server parser only: Workers AI and other models stay off, so this call has no model charge. Returns previewUrl (/tools/p/{token}), claimUrl, and signUpUrl. claimUrl and signUpUrl are the same sign-up link (/login?next=/tools/p/{token}&utm_source=mcp) labeled sign up free to publish. The parsed form is stored for 24 hours and the daily cleanup deletes it. The URL is fetched once. File contents are not logged. Restricted fields such as Social Security numbers are left out. Anonymous use is limited per network and by a daily cap; over the cap, sign up free.

Set an application's status for the authenticated organization. Requires an org API key with the applications:write scope. A decline requires a decline reason. This writes the status; it does not delete the application.

Update a form that belongs to the authenticated organization. Requires an org API key or OAuth sign-in with the forms:write scope. Same checks as PATCH /api/v1/forms/{id}: title, settings, and fields. A field entry with an id updates that field. A field entry with no id inserts a field. op add also inserts a field, and that row must not include an id. The server assigns the id. Required on an insert: label and type (an existing field type). Optional on an insert: helpText (at most 2000 characters), required, options, and stageId. stageId defaults to the Interest stage, or the first stage. New fields are appended. order on an insert is ignored. On an existing field, optional order is an integer greater than or equal to 0 and sets that field's position. An order already used by another field on this version is refused (409 'A field already occupies this order on the form version.'). op remove, or removeFieldIds, deletes fields on the current draft. Answers and consents are matched by field key on every version of the form, not by the draft field id. A field that has answers or consents cannot be removed (409 'This field has answers or consents and cannot be removed.'). Changing a field key is refused when that field's current key, or the new key, already has answers or consents on this form (409 'A field key that already has answers or consents cannot be changed.'). At most 20 fields can be added and 20 removed in one call. A form can hold at most 140 fields. Title is at most 200 characters, a field label at most 500, and stored settings JSON at most 32 KB. A field id that is not on the current draft returns 409 'This field id is not on the current draft.' Re-read the form with get_form and retry with the current field ids. A malformed field id is rejected. Top-level settings keys whose names start with __ are ignored, and the stored editor stamp is kept. A lower editorSeq does not overwrite a newer save. A form that belongs to another organization is not found. MCP, an org API key, and OAuth share a limit of 60 updates per organization per hour. Adding or removing fields uses that same limit. A website session is not counted. Returns the updated draft, any new field ids, and editorUrl (/app/forms/{formId}). Does not publish the form.

Get one application by id when it belongs to the authenticated organization. Requires an org API key with the applications:read scope.

Get one form by id when it belongs to the authenticated organization. Requires an org API key with the forms:read scope. When the form is published and not soft-deleted, also returns publicUrl, publicFormUrl, embedUrl, and embedSnippet, and a draft that was never published omits those fields. A soft-deleted form omits those fields too.

Read an unexpired converter preview by previewId. No API key. Returns the title, fields, stages, expiresAt, and previewUrl already shown on the public preview page (/tools/p/{previewId}), whether or not that preview was claimed. Unknown or expired ids are not found and include the converter URL. Does not return organization ids or saved form ids.

List applications for one form in the authenticated organization. Requires an org API key with the applications:read scope.

List forms that belong to the authenticated organization. Requires an org API key with the forms:read scope. When a form is published and not soft-deleted, that item also includes publicUrl, publicFormUrl, embedUrl, and embedSnippet, and a draft that was never published omits those fields. A soft-deleted form omits those fields too.