ApplyToVolunteer Applications API

openapi: 3.2.0
info:
  title: Apply2Volunteer Applications 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: Applications
paths:
  /api/v1/applications/{id}:
    get:
      operationId: getApplication
      summary: Get an application
      description: Get an application. Requires a browser session or an org API key with applications:read. A missing or wrong key is 404, not 401.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Application id.
        required: true
        description: Application id.
        name: id
        in: path
      responses:
        '200':
          description: Get an application
        '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:
      - Applications
    patch:
      operationId: updateApplicationStatus
      summary: Update an application status
      description: Update application status (FCRA-gated decline). Requires a browser session or an org API key with applications:write. A missing or wrong key is 404, not 401. Declining requires declineReason background_check, not_a_fit, or incomplete.
      security:
      - orgApiKey: []
      parameters:
      - schema:
          type: string
          description: Application id.
        required: true
        description: Application id.
        name: id
        in: path
      requestBody:
        required: true
        description: JSON object with status, notes, or declineReason.
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - new
                  - in_review
                  - advanced
                  - accepted
                  - declined
                  - withdrawn
                  - on_hold
                  description: Next application status. Omitted status keeps the current one.
                notes:
                  type: string
                  description: Reviewer notes. Omitted notes keep the current notes.
                declineReason:
                  type: string
                  description: Required when status is declined. The handler accepts only background_check, not_a_fit, incomplete. Any other value is 400, or 409 when the reason is usable but the background-check gate blocks the decline.
              description: At least one of status, notes, or declineReason. The handler rejects a body that is not this object.
      responses:
        '200':
          description: Update application status (FCRA-gated decline)
        '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:
      - Applications
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.