---
title: "Grade a volunteer form"
method: POST
path: "/api/v1/tools/grade"
---

# Grade a volunteer form

`POST /api/v1/tools/grade`

## Request

- Base URL: `https://applytovolunteer.com`
- URL: `https://applytovolunteer.com/api/v1/tools/grade`
- Auth: one of:
  - HTTP bearer
  - none

Form Grader (upload, URL, pasted, or form id). id and reportUrl (/tools/r/{id}) are present only for public grades. Saved-form grades omit id and reportUrl; owners use GET /api/v1/forms/{id}/grade. Anonymous grades omit restricted field labels from parsed; the score still counts them. The API key is optional. Anonymous calls need a Turnstile token in production. A failed check is 400 with error turnstile. A missing Turnstile configuration is 503. Dev and test skip verification. Keyless agents should use /mcp or POST /a2a instead of calling this route without a token. formId or formVersionId requires forms:read and does not use Turnstile. A key without forms:read is treated as anonymous.

## Request body

- object: Send one input. Precedence is formId or formVersionId, then pasted or form, then url, then text. Do not send website; a non-empty string is rejected. Anonymous calls need turnstileToken in production. Saved-form grades do not.
  - `url` string: Page or file URL to grade or convert.
  - `text` string: Plain text of the form. Used when url, pasted, and form are absent.
  - `pasted` unknown
  - `form` unknown
  - `formId` string: Saved form id. Requires an org API key with forms:read. Not anonymous. Convert rejects this.
  - `formVersionId` string: Saved form version id. Requires an org API key with forms:read. Convert rejects this.
  - `turnstileToken` string: Cloudflare Turnstile token. Required in production. Dev and test (ENVIRONMENT exactly dev or test) skip verification. A failed check is 400 with error turnstile. A missing Turnstile configuration is 503 with error turnstile_misconfigured. This token is not an org API key.

## Response `200`

Form Grader (upload, URL, pasted, or form id). id and reportUrl (/tools/r/{id}) are present only for public grades. Saved-form grades omit id and reportUrl; owners use GET /api/v1/forms/{id}/grade. Anonymous grades omit restricted field labels from parsed; the score still counts them.

- object
  - `id` string
  - `report` object, required
  - `parsed` object, required
  - `convertPath` string, required
  - `reportUrl` string

## Other responses

- `400`: The body, query, or input failed validation.
- `401`: No signed-in session and no live org API key.
- `415`: The file type is not a PDF, Word document, or HTML page this route accepts.
- `422`: The upload contains filled-in personal data. Send a blank form.
- `429`: Too many requests from this network or organization.
- `503`: Turnstile is not configured, or a required parser is unavailable.

---

[API](https://skmtc.dev/applytovolunteer/apis/apply2volunteer-api.md) · [All operations](https://skmtc.dev/applytovolunteer/apis/apply2volunteer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/applytovolunteer/apis/apply2volunteer-api/revisions/23df1ec8c88d?raw)