openapi: 3.0.3
info:
  title: Qgiv API
  description: >-
    The Qgiv API is a token-authenticated, form-scoped service for reading and
    writing data behind Qgiv (now Bloomerang Fundraising) donation forms,
    events, and peer-to-peer campaigns. Qgiv was acquired by Bloomerang in
    January 2024; this legacy API documented at qgiv.com/api remains the
    programmatic interface for Qgiv accounts. All requests are made with HTTP
    POST to https://secure.qgiv.com/admin/api, carrying a `token` field bound
    to one or more forms. Input is accepted as XML or JSON via a `package`
    field for write operations; output format is selected by the URL file
    extension (`.xml` or `.json`), independent of the request's input format.
    There is no bearer/OAuth layer, no documented API versioning scheme, and
    no documented public webhook subscription endpoint - some endpoints are
    modeled here directly from the vendor's own documentation examples
    (marked Confirmed), and request/response bodies for write operations not
    fully illustrated in the docs are modeled by API Evangelist from the
    documented example payloads (marked Modeled).
  version: '1.0'
  contact:
    name: Qgiv (Bloomerang Fundraising)
    url: https://www.qgiv.com/api/
  license:
    name: Proprietary
    url: https://www.qgiv.com/terms-of-service
servers:
  - url: https://secure.qgiv.com/admin/api
    description: Qgiv production API
security:
  - tokenAuth: []
tags:
  - name: Transactions
    description: Confirmed. Read-only reporting on donation transactions.
  - name: Recurring
    description: Confirmed. Read-only reporting on recurring donation schedules.
  - name: Refunds
    description: Confirmed. Read-only reporting on refunds.
  - name: Registrations
    description: Confirmed. Read-only reporting on peer-to-peer registrations.
  - name: Events
    description: Confirmed. Manage fundraising/ticketed events.
  - name: Account Settings
    description: Confirmed. Read and update organization and form settings.
  - name: Custom Fields
    description: Confirmed. Manage custom fields on a donation form.
  - name: Custom Amounts
    description: Confirmed. Manage preset suggested-giving amounts.
  - name: Statements
    description: Confirmed. Read-only reporting on monthly processing statements.
  - name: Mappings
    description: Confirmed. Manage export/report mappings to external systems.
paths:
  /reporting/transactions/last/{limit}:
    get:
      operationId: getLastTransactions
      tags: [Transactions]
      summary: Get last N transactions (Confirmed)
      description: Returns the last [limit] transactions for the current form or organization.
      parameters:
        - name: limit
          in: path
          required: true
          description: Number of transactions to return. Integer greater than 0.
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/transactions/after/{transactionId}:
    get:
      operationId: getTransactionsAfterId
      tags: [Transactions]
      summary: Get transactions after a given ID (Confirmed)
      description: Returns transactions with IDs greater than the specified transaction ID.
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/transactions/dates/{begin}:{end}:
    get:
      operationId: getTransactionsByDateRange
      tags: [Transactions]
      summary: Get transactions by date range (Confirmed)
      description: >-
        Returns transactions between begin and end dates, formatted MMDDYYYY
        or MM-DD-YYYY, with optional "MMDDYYYY HHIISS" timestamps.
      parameters:
        - name: begin
          in: path
          required: true
          schema:
            type: string
            example: '01012012'
        - name: end
          in: path
          required: true
          schema:
            type: string
            example: '12312012'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/transactions/{id}:
    get:
      operationId: getTransaction
      tags: [Transactions]
      summary: Get a single transaction (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /reporting/recurring/list:
    post:
      operationId: listRecurringTransactions
      tags: [Recurring]
      summary: List all recurring transactions (Confirmed)
      description: Returns all recurring transactions for the current form or organization, plus an upcoming billing forecast by month.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: Recurring transactions and forecast.
          content:
            application/json:
              schema:
                type: object
                properties:
                  forecast:
                    type: object
                    additionalProperties:
                      type: string
                  recurringTransactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecurringTransaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/recurring/{status}:
    post:
      operationId: listRecurringTransactionsByStatus
      tags: [Recurring]
      summary: List recurring transactions by status (Confirmed)
      parameters:
        - name: status
          in: path
          required: true
          schema:
            type: string
            enum: [active, paused, expired, deleted]
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: Recurring transactions matching the status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  recurringTransactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecurringTransaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/recurring/{id}:
    post:
      operationId: getRecurringTransaction
      tags: [Recurring]
      summary: Get a single recurring transaction (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested recurring transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  recurring:
                    $ref: '#/components/schemas/RecurringTransaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /reporting/refunds/last/{limit}:
    post:
      operationId: getLastRefunds
      tags: [Refunds]
      summary: Get last N refunds (Confirmed)
      parameters:
        - name: limit
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of refunds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  refunds:
                    type: array
                    items:
                      $ref: '#/components/schemas/Refund'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/refunds/after/{refundId}:
    post:
      operationId: getRefundsAfterId
      tags: [Refunds]
      summary: Get refunds after a given ID (Confirmed)
      parameters:
        - name: refundId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of refunds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  refunds:
                    type: array
                    items:
                      $ref: '#/components/schemas/Refund'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/refunds/dates/{begin}:{end}:
    post:
      operationId: getRefundsByDateRange
      tags: [Refunds]
      summary: Get refunds by date range (Confirmed)
      parameters:
        - name: begin
          in: path
          required: true
          schema:
            type: string
        - name: end
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of refunds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  refunds:
                    type: array
                    items:
                      $ref: '#/components/schemas/Refund'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/refunds/{id}:
    post:
      operationId: getRefund
      tags: [Refunds]
      summary: Get a single refund (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested refund.
          content:
            application/json:
              schema:
                type: object
                properties:
                  refund:
                    $ref: '#/components/schemas/Refund'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /reporting/registrations/last/{limit}:
    post:
      operationId: getLastRegistrations
      tags: [Registrations]
      summary: Get last N peer-to-peer registrations (Confirmed)
      parameters:
        - name: limit
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of registrations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  registrations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Registration'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/registrations/dates/{begin}:{end}:
    post:
      operationId: getRegistrationsByDateRange
      tags: [Registrations]
      summary: Get peer-to-peer registrations by date range (Confirmed)
      parameters:
        - name: begin
          in: path
          required: true
          schema:
            type: string
        - name: end
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of registrations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  registrations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Registration'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/registrations/{id}:
    post:
      operationId: getRegistration
      tags: [Registrations]
      summary: Get a single peer-to-peer registration (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested registration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  registration:
                    $ref: '#/components/schemas/Registration'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /events/list:
    post:
      operationId: listEvents
      tags: [Events]
      summary: List all events (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /events/{id}:
    get:
      operationId: getEvent
      tags: [Events]
      summary: Retrieve a single event (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested event.
          content:
            application/json:
              schema:
                type: object
                properties:
                  event:
                    $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateEvent
      tags: [Events]
      summary: Update an event (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The updated event.
          content:
            application/json:
              schema:
                type: object
                properties:
                  event:
                    $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /account/settings:
    get:
      operationId: getAccountSettings
      tags: [Account Settings]
      summary: Get organization and form settings (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: Organization and per-form settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  settings:
                    $ref: '#/components/schemas/AccountSettings'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: updateAccountSettings
      tags: [Account Settings]
      summary: Update organization and form settings (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The updated settings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  settings:
                    $ref: '#/components/schemas/AccountSettings'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /customFields/list:
    post:
      operationId: listCustomFields
      tags: [Custom Fields]
      summary: List all custom fields (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of custom fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customField:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomField'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customFields/create:
    post:
      operationId: createCustomField
      tags: [Custom Fields]
      summary: Create a custom field (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The created custom field(s).
          content:
            application/json:
              schema:
                type: object
                properties:
                  customField:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomField'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /customFields/{id}:
    get:
      operationId: getCustomField
      tags: [Custom Fields]
      summary: Retrieve a single custom field (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested custom field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customField:
                    $ref: '#/components/schemas/CustomField'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateCustomField
      tags: [Custom Fields]
      summary: Update a custom field (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The updated custom field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customField:
                    $ref: '#/components/schemas/CustomField'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /amounts/list:
    get:
      operationId: listCustomAmounts
      tags: [Custom Amounts]
      summary: List all custom amounts (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of custom amounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  amounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomAmount'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /amounts/create:
    post:
      operationId: createCustomAmount
      tags: [Custom Amounts]
      summary: Create custom amount(s) (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The created custom amount(s).
          content:
            application/json:
              schema:
                type: object
                properties:
                  amounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomAmount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /amounts/{id}:
    get:
      operationId: getCustomAmount
      tags: [Custom Amounts]
      summary: Get a single custom amount (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested custom amount.
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomAmount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateCustomAmount
      tags: [Custom Amounts]
      summary: Update a custom amount (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The updated custom amount.
          content:
            application/json:
              schema:
                type: object
                properties:
                  amount:
                    $ref: '#/components/schemas/CustomAmount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /reporting/statements/list:
    post:
      operationId: listStatements
      tags: [Statements]
      summary: List all statements (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of statements.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Statement'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/statements/latest:
    post:
      operationId: getLatestStatements
      tags: [Statements]
      summary: Get the latest statement(s) (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The latest statement(s).
          content:
            application/json:
              schema:
                type: object
                properties:
                  statements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Statement'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/statements/{id}:
    post:
      operationId: getStatement
      tags: [Statements]
      summary: Get a single statement (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested statement.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Statement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /reporting/mappings/list:
    get:
      operationId: listMappings
      tags: [Mappings]
      summary: List all report mappings (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: A list of mappings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mappings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Mapping'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /reporting/mappings/{id}:
    get:
      operationId: getMapping
      tags: [Mappings]
      summary: Retrieve a single mapping (Confirmed)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenOnlyRequest'
      responses:
        '200':
          description: The requested mapping.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mapping:
                    $ref: '#/components/schemas/Mapping'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /mappings/create:
    post:
      operationId: createMapping
      tags: [Mappings]
      summary: Create a mapping (Confirmed)
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The created mapping(s).
          content:
            application/json:
              schema:
                type: object
                properties:
                  mappings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Mapping'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /mappings/{id}:
    post:
      operationId: updateMapping
      tags: [Mappings]
      summary: Update a mapping (Confirmed)
      description: >-
        Modeled. The documentation shows the request payload for updating a
        mapping by ID but does not show the full response example separately
        from the create response; the response is modeled on the list/get
        Mapping shape.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageRequest'
      responses:
        '200':
          description: The updated mapping.
          content:
            application/json:
              schema:
                type: object
                properties:
                  mappings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Mapping'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: >-
        Documented as a POST body field (`token=<API token>`), not a header or
        querystring value. Modeled here as an apiKey scheme because OpenAPI
        3.0 has no first-class "form field" security type. The token is
        scoped to one or more specific forms in the Qgiv admin console.
  schemas:
    TokenOnlyRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
          description: API token bound to the form(s) being accessed.
    PackageRequest:
      type: object
      required: [token, package]
      properties:
        token:
          type: string
          description: API token bound to the form(s) being accessed.
        package:
          type: string
          description: XML- or JSON-formatted input payload for the write operation.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    Transaction:
      type: object
      properties:
        id:
          type: string
        amount:
          type: string
        date:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        paymentMethod:
          type: string
        formId:
          type: string
        status:
          type: string
      description: Modeled. Vendor docs describe field categories but do not publish a full example field list for a single transaction object.
    RecurringTransaction:
      type: object
      properties:
        id:
          type: string
        startDate:
          type: string
        endDate:
          type: string
        nextBilling:
          type: string
        frequency:
          type: string
        amount:
          type: string
        donorName:
          type: string
        state:
          type: string
          enum: [active, paused, expired, deleted]
    Refund:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        refundDate:
          type: string
        transactionId:
          type: string
        paymentMethod:
          type: string
        amount:
          type: string
      description: Modeled. Vendor docs describe the field categories returned (name, refund date, transaction ID, payment method) without a full worked JSON example.
    Registration:
      type: object
      properties:
        id:
          type: string
        formId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        address:
          type: object
          additionalProperties: true
        fundraisingGoal:
          type: string
        team:
          type: object
          additionalProperties: true
        category:
          type: string
        promoCode:
          type: string
        totalOnline:
          type: string
        totalOffline:
          type: string
      description: Modeled from the vendor's documented response field categories (registrant, team, category, promo codes, totals).
    Event:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        startDate:
          type: string
        endDate:
          type: string
        address:
          type: object
          additionalProperties: true
        prices:
          type: array
          items:
            type: object
            additionalProperties: true
        packages:
          type: array
          items:
            type: object
            additionalProperties: true
        fields:
          type: array
          items:
            type: object
            additionalProperties: true
        promoCodes:
          type: array
          items:
            type: object
            additionalProperties: true
        organization:
          type: object
          additionalProperties: true
    AccountSettings:
      type: object
      properties:
        organization:
          type: object
          properties:
            title:
              type: string
            contactEmail:
              type: string
            contactURL:
              type: string
        forms:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              activeDonation:
                type: string
              restrictionClass:
                type: string
    CustomField:
      type: object
      properties:
        id:
          type: string
        reference:
          type: string
        title:
          type: string
        content:
          type: string
        amountToBecomeRequired:
          type: string
        inputType:
          type: string
        displayBlock:
          type: string
        isRequired:
          type: string
        displayOnFrontend:
          type: string
        displayOnVT:
          type: string
        displayOnKiosk:
          type: string
        displayMobile:
          type: string
        sort:
          type: string
        state:
          type: string
    CustomAmount:
      type: object
      properties:
        id:
          type: string
        value:
          type: string
        title:
          type: string
        description:
          type: string
        state:
          type: string
        sort:
          type: string
    Statement:
      type: object
      properties:
        id:
          type: string
        amountContributed:
          type: string
        percentage:
          type: string
        transactionFees:
          type: string
        date:
          type: string
        transactionSummary:
          type: object
          properties:
            transactions:
              type: array
              items:
                type: object
                additionalProperties: true
            totalTransactions:
              type: integer
            subTotal:
              type: number
            total:
              type: number
    Mapping:
      type: object
      properties:
        id:
          type: string
        identifier:
          type: string
        mappingData:
          type: string
        exportService:
          type: string
        type:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'