ApplyToVolunteer Forms API

openapi: 3.2.0
info:
  title: Apply2Volunteer Forms API
  version: 1.0.0
  description: 'Convert volunteer PDFs into progressive online forms. Organization owners and admins create API keys in the dashboard. Send a key as Authorization: Bearer a2v_... The token starts with a2v_. This API does not implement OAuth. Public submit and anonymous grade or convert do not accept the key in place of a Turnstile token. Keyless agents use /mcp and POST /a2a for anonymous grade and preview.'
  license:
    name: Proprietary
    url: https://applytovolunteer.com/terms
servers:
- url: https://applytovolunteer.com
security:
- orgApiKey: []
tags:
- name: Forms
paths:
  /api/v1/forms:
    get:
      operationId: listForms
      summary: List forms in an organization
      description: List org forms. Requires a browser session or an org API key with forms:read. A missing or wrong key is 404, not 401.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Organization id.
        required: true
        description: Organization id.
        name: orgId
        in: query
      responses:
        '200':
          description: List org forms
        '400':
          description: The body, query, or input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
    post:
      operationId: createForm
      summary: Create a form from a conversion or a blank form
      description: Create a form from a conversion or blank. Requires forms:write on the orgId in the body. No session and no key is 401. A key for another organization is 404. A key missing forms:write is 403. A blank create from an org API key shares 60 per organization per hour with MCP. A website session is not counted.
      security:
      - orgApiKey: []
      requestBody:
        required: true
        description: JSON object. orgId is required.
        content:
          application/json:
            schema:
              type: object
              properties:
                orgId:
                  type: string
                  description: Organization id. The key must belong to this organization and include forms:write.
                conversionId:
                  type: string
                  description: Finished conversion to copy. Ignored when fromReportId or fromPreviewId is set.
                title:
                  type: string
                  maxLength: 200
                  description: Form title, at most 200 characters. Falls back to the source title, then Volunteer application.
                blank:
                  type: boolean
                  description: Accepted and ignored. A blank form is created when conversionId, fromReportId, and fromPreviewId are all omitted.
                fromReportId:
                  type: string
                  description: Public grade report to rebuild from. Wins over fromPreviewId and conversionId.
                fromPreviewId:
                  type: string
                  description: Converter preview to rebuild from. Used when fromReportId is omitted. Wins over conversionId.
              required:
              - orgId
              description: JSON object. orgId is required. Omit the three source ids to create a blank form.
      responses:
        '200':
          description: Create a form from a conversion or blank
        '400':
          description: The body, query, or input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: No signed-in session and no live org API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: The API key is missing a required scope, or the action is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests from this network or organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
  /api/v1/forms/{id}:
    get:
      operationId: getForm
      summary: Get a form and its current version
      description: Get a form and its current version. Requires a browser session or an org API key with forms:read. A missing or wrong key is 404, not 401.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Form id.
        required: true
        description: Form id.
        name: id
        in: path
      responses:
        '200':
          description: Get a form and its current version
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
    patch:
      operationId: updateForm
      summary: Update a form title, settings, or fields
      description: Update form title, settings, or fields. Add a field by omitting its id. op add also inserts a field and must not include an id. Remove a field with op remove or removeFieldIds. New field ids are returned on added. Requires a browser session or an org API key with forms:write. A missing or wrong key is 404, not 401. An org API key shares 60 updates per organization per hour with MCP, including adds and removes. A website session is not counted. A field id that is not on the current draft is 409. A field whose key has answers or consents on any version of the form cannot be removed. A field key that already has answers or consents cannot be changed. Help text is at most 2000 characters.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Form id.
        required: true
        description: Form id.
        name: id
        in: path
      requestBody:
        required: true
        description: JSON object with title, settings, fields, or removeFieldIds.
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  maxLength: 200
                  description: Form title, at most 200 characters. On a published form this is held as a draft until publish.
                settings:
                  type: object
                  properties:
                    description:
                      type:
                      - string
                      - 'null'
                      description: Public description. Null or an empty string clears the drafted description.
                    indexable:
                      type: boolean
                      description: Whether the published form may be indexed.
                    confirmationMessage:
                      type:
                      - string
                      - 'null'
                      description: Confirmation copy. Null or an empty string clears the drafted message.
                    notifyEmails:
                      type: array
                      items:
                        type: string
                      description: Addresses notified of a new application. Replaces the live list.
                  description: description, indexable, confirmationMessage, and notifyEmails are type-checked. Other keys are stored on the live settings object. editorSession, editorSeq, and any top-level key whose name starts with __ are ignored. The stored settings JSON is at most 32 KB.
                fields:
                  type: array
                  items:
                    type: object
                    properties:
                      op:
                        type: string
                        enum:
                        - add
                        - update
                        - remove
                        description: add inserts a field. remove deletes it. update, or omitted with an id, patches that field. Omitted with no id inserts.
                      id:
                        type: string
                        description: Field id on the current draft. Required to update or remove. An op add row must omit id. The server assigns a new id.
                      type:
                        type: string
                        enum:
                        - short_text
                        - long_text
                        - email
                        - phone
                        - number
                        - date
                        - single_select
                        - multi_select
                        - yes_no
                        - address
                        - availability_grid
                        - file
                        - signature
                        - consent
                        description: Known field type. Unknown strings are rejected.
                      label:
                        type: string
                        maxLength: 500
                        description: Non-blank label, at most 500 characters. Omitted labels stay as stored.
                      helpText:
                        type:
                        - string
                        - 'null'
                        maxLength: 2000
                        description: Help text, at most 2000 characters. Null clears it.
                      required:
                        type:
                        - boolean
                        - 'null'
                        description: Whether the field is required. Null is accepted.
                      options:
                        type:
                        - array
                        - 'null'
                        items:
                          type: string
                        description: Choice options. Select and choice types need a non-empty list when type or options is sent. yes_no ignores stored options.
                      stageId:
                        type:
                        - string
                        - 'null'
                        description: Stage id on this form version. Null is rejected. An unknown stage id is rejected.
                      order:
                        type: integer
                        minimum: 0
                        description: Zero-based order. Two fields cannot share an order.
                      key:
                        type: string
                        description: Stable field key. Blank keys are rejected.
                      sensitive:
                        anyOf:
                        - type: boolean
                          enum:
                          - false
                        - type: string
                          enum:
                          - dob
                          - ssn
                          - drivers_license
                          - criminal_history
                          - abuse_cps
                          - driving_record
                          - medical
                          - minor_info
                          - financial
                          - protected_class
                          - other
                        - type: 'null'
                        description: false or null clears sensitivity. Otherwise one of the known sensitive kinds.
                      consentKind:
                        description: Known consent kind, or null to clear it.
                        anyOf:
                        - type: string
                          enum:
                          - general_waiver
                          - background_check_authorization
                          - photo_release
                          - code_of_conduct
                          - confidentiality
                          - medical_release
                          - custom
                        - type: 'null'
                      consentText:
                        type:
                        - string
                        - 'null'
                        description: Consent copy. Null clears it.
                    additionalProperties: false
                    description: Partial field update, or an insert. An insert requires label and type. helpText, required, options, and stageId are optional. stageId defaults to the Interest stage, or the first stage. New fields are appended. Unknown keys, including grid and validation, are rejected. Omitted keys are not written on an update. At most 20 inserts per call.
                  description: Field rows to update, add, or remove. The value must be an array when present. At most 20 adds per call. A form can hold at most 140 fields.
                removeFieldIds:
                  type: array
                  items:
                    type: string
                  description: Field ids to delete from the current draft. A field whose key has answers or consents on any version of this form is 409. A field id that is not on the draft is 409. A malformed id is 400. Combined with op remove, at most 20 deletes per call.
              description: JSON object. An empty object changes nothing. title must be a string when present. Added field ids are returned on added. Adding or removing fields counts toward the shared 60 updates per organization per hour.
      responses:
        '200':
          description: Update form title, settings, or fields. Add a field by omitting its id. op add also inserts a field and must not include an id. Remove a field with op remove or removeFieldIds. New field ids are returned on added.
        '400':
          description: The body, query, or input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: The write conflicts with the current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests from this network or organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
  /api/v1/forms/{id}/publish:
    post:
      operationId: publishForm
      summary: Publish a new locked form version
      description: Publish a new locked version. A form with no fields is rejected. Publish is refused when it would remove a field that already has answers or consents. Requires a browser session or an org API key with forms:write. A missing or wrong key is 404, not 401. No request fields are read. A form with no fields is 400. Dropping a field key that already has answers or consents is 409.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Form id.
        required: true
        description: Form id.
        name: id
        in: path
      requestBody:
        required: false
        description: No request body. The handler does not read one.
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
              description: No fields. The handler does not read a body.
      responses:
        '200':
          description: Publish a new locked version. A form with no fields is rejected. Publish is refused when it would remove a field that already has answers or consents.
        '400':
          description: The body, query, or input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: The write conflicts with the current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests from this network or organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: The form could not be published.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
  /api/v1/forms/{id}/repair-identities:
    post:
      operationId: repairFormFieldIdentities
      summary: Remint invalid draft field ids
      description: Remint invalid draft field ids (owner). Requires a browser session or an org API key with forms:write. A missing or wrong key is 404, not 401. No request fields are read.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Form id.
        required: true
        description: Form id.
        name: id
        in: path
      requestBody:
        required: false
        description: No request body. The handler does not read one.
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
              description: No fields. The handler does not read a body.
      responses:
        '200':
          description: Remint invalid draft field ids (owner)
        '400':
          description: The body, query, or input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: The write conflicts with the current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
  /api/v1/forms/{id}/discard:
    post:
      operationId: discardFormDraft
      summary: Discard the open draft version
      description: Discard the open draft version. Requires a browser session or an org API key with forms:write. A missing or wrong key is 404, not 401. No request fields are read.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Form id.
        required: true
        description: Form id.
        name: id
        in: path
      requestBody:
        required: false
        description: No request body. The handler does not read one.
        content:
          application/json:
            schema:
              type: object
              properties: {}
              additionalProperties: false
              description: No fields. The handler does not read a body.
      responses:
        '200':
          description: Discard the open draft version
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
  /api/v1/forms/{id}/grade:
    get:
      operationId: gradeSavedForm
      summary: Grade the current saved form version
      description: Owner/org grade for the current form version (auth). Use this for org-internal grades; they have no public /tools/r/{id} share link. Requires a browser session or an org API key with forms:read. A missing or wrong key is 404, not 401.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Form id.
        required: true
        description: Form id.
        name: id
        in: path
      responses:
        '200':
          description: Owner/org grade for the current form version (auth). Use this for org-internal grades; they have no public /tools/r/{id} share link.
        '400':
          description: The body, query, or input failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '415':
          description: The file type is not a PDF, Word document, or HTML page this route accepts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: The upload contains filled-in personal data. Send a blank form.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests from this network or organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Turnstile is not configured, or a required parser is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
  /api/v1/forms/{id}/applications:
    get:
      operationId: listFormApplications
      summary: List applications for a form
      description: List applications for a form. Requires a browser session or an org API key with applications:read. A missing or wrong key is 404, not 401. forms:read does not include this scope.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Form id.
        required: true
        description: Form id.
        name: id
        in: path
      - schema:
          type: string
          description: Exact application status to keep.
        required: false
        description: Exact application status to keep.
        name: status
        in: query
      - schema:
          type: string
          description: Case-insensitive match against the applicant name and email.
        required: false
        description: Case-insensitive match against the applicant name and email.
        name: q
        in: query
      responses:
        '200':
          description: List applications for a form
        '404':
          description: The resource does not exist, or it is hidden from this caller. Several organization routes return 404 instead of 401 when the key is missing or the row is in another organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Forms
components:
  schemas:
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Short error code or message.
        message:
          type: string
          description: Human-readable detail when the handler sends one.
        fields:
          type: object
          additionalProperties:
            type: string
          description: Field-level validation messages.
        retryable:
          type: boolean
          description: Set on some public submit conflicts.
      required:
      - error
  securitySchemes:
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: a2v API key
      description: Organization API key. REST reads Authorization and accepts only the exact prefix "Bearer " (capital B, one space) followed by a token that starts with a2v_. Put the a2v_ token in the bearer credential. Do not include the word Bearer in the token. Owners and admins create keys at /app/settings/api-keys. The secret is shown once. Revoked keys are rejected. This API does not implement OAuth. Scopes are forms:read, forms:write, applications:read, and applications:write. forms:write does not include forms:read. A new key defaults to forms:read and forms:write. applications:read and applications:write are opt-in. A browser session cookie is also accepted on organization routes. Agents send the bearer key.