> ## Documentation Index
> Fetch the complete documentation index at: https://developers.getbreezyapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Page form responses

> Captured visit forms with complete questions, recorded answers, original work relationships, and current required-data completeness. Current templates do not replace captured content. Unsupported capture returns null questions and completeness while retaining safe metadata. Orders by id ascending. List and detail return the same complete representation. updated_since covers parent-row saves only.



## OpenAPI

````yaml /openapi.json get /form-responses
openapi: 3.0.3
info:
  title: Breezy Public Reporting API
  version: 1.0.0
  description: >-
    Read customers, team members, jobs, visits, assignments, installed
    equipment, captured form responses, time entries, configured-period
    timesheets, business reference catalogs, job leads, estimates, invoices,
    payments, refunds, recorded job financials, saved sold/earned credits, and
    financial summaries for your company. Existing API keys grant company-wide
    read access. Amounts are integer USD cents. Reads return current corrected
    records, with cursor pagination for collecting results.


    Read the [Breezy FSM guides](https://developers.getbreezyapp.com) for
    authentication, pagination, refresh limits, and business measures. All reads
    use latest corrected company records; cursors do not create a snapshot or a
    complete change feed.
servers:
  - url: https://api.getbreezyapp.com/v1
    description: Breezy FSM production API
security:
  - apiKey: []
tags:
  - name: Company
  - name: Invoices
  - name: Payments
  - name: Refunds
  - name: Reports
  - name: TeamMembers
  - name: Accounts
  - name: Contacts
  - name: Locations
  - name: Jobs
  - name: JobAppointments
  - name: JobAssignments
  - name: BusinessUnits
  - name: JobTypes
  - name: JobClasses
  - name: JobLifecycles
  - name: LeadSources
  - name: Tags
  - name: Estimates
  - name: JobLeads
  - name: Equipment
  - name: FormResponses
  - name: TimeEntries
  - name: Timesheets
  - name: JobFinancials
  - name: RevenueAttributions
externalDocs:
  description: Breezy FSM reporting guides and API reference
  url: https://developers.getbreezyapp.com
paths:
  /form-responses:
    get:
      tags:
        - FormResponses
      summary: Page form responses
      description: >-
        Captured visit forms with complete questions, recorded answers, original
        work relationships, and current required-data completeness. Current
        templates do not replace captured content. Unsupported capture returns
        null questions and completeness while retaining safe metadata. Orders by
        id ascending. List and detail return the same complete representation.
        updated_since covers parent-row saves only.
      operationId: listFormResponses
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            description: >-
              Maximum parent records or report rows. Complete children are
              always included.
          required: false
          description: >-
            Maximum parent records or report rows. Complete children are always
            included.
          name: limit
          in: query
        - schema:
            type: string
            nullable: true
            minLength: 1
            default: null
            description: >-
              Repeat the original filters; any valid page size may continue.
              Foreign-company, tampered or mismatched cursors return
              INVALID_CURSOR.
          required: false
          description: >-
            Repeat the original filters; any valid page size may continue.
            Foreign-company, tampered or mismatched cursors return
            INVALID_CURSOR.
          name: cursor
          in: query
        - schema:
            type: array
            nullable: true
            items:
              type: string
              format: uuid
            minItems: 1
            maxItems: 100
            default: null
            description: >-
              Repeat ids for a bounded ID set. Valid foreign or missing IDs
              contribute no list rows.
          required: false
          style: form
          explode: true
          name: ids
          in: query
        - schema:
            type: string
            nullable: true
            format: date-time
            default: null
            description: Inclusive creation instant.
          required: false
          description: Inclusive creation instant.
          name: created_from
          in: query
        - schema:
            type: string
            nullable: true
            format: date-time
            default: null
            description: Exclusive creation instant.
          required: false
          description: Exclusive creation instant.
          name: created_before
          in: query
        - schema:
            type: string
            nullable: true
            format: date-time
            default: null
            description: >-
              Inclusive parent-record updated_at filter only; not a complete
              change feed.
          required: false
          description: >-
            Inclusive parent-record updated_at filter only; not a complete
            change feed.
          name: updated_since
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: account_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: business_unit_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: job_type_id
          in: query
        - schema:
            type: string
            nullable: true
            enum:
              - SERVICE
              - MAINTENANCE
              - ESTIMATE_REPAIR
              - ESTIMATE_REPLACE
              - INSTALL
              - WARRANTY
              - CALLBACK
              - SALES
              - UNKNOWN
              - null
          required: false
          name: job_class
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: appointment_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
            description: >-
              Original captured appointment’s job; follow-up reuse does not
              duplicate responses.
          required: false
          description: >-
            Original captured appointment’s job; follow-up reuse does not
            duplicate responses.
          name: job_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: location_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: form_id
          in: query
        - schema:
            type: string
            nullable: true
            format: uuid
            default: null
          required: false
          name: last_edited_by_id
          in: query
        - schema:
            type: boolean
            nullable: true
            default: null
          required: false
          name: ad_hoc
          in: query
      responses:
        '200':
          description: Successful read. Clients ignore unrecognized response fields.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormResponsePage'
              example:
                data:
                  - id: 11111111-1111-4111-8111-000000004103
                    form_id: 11111111-1111-4111-8111-000000004104
                    name: Air conditioning inspection
                    instance_number: 2
                    label: Downstairs condenser
                    ad_hoc: true
                    appointment_id: 11111111-1111-4111-8111-000000001109
                    job_id: 11111111-1111-4111-8111-000000000501
                    account_id: 11111111-1111-4111-8111-000000000101
                    location_id: 11111111-1111-4111-8111-000000001107
                    last_edited_by:
                      id: 11111111-1111-4111-8111-000000000401
                      name: Alex Example
                    created_at: '2026-08-20T14:00:00Z'
                    updated_at: '2026-09-08T19:00:00Z'
                    completed: false
                    questions:
                      - question_id: 11111111-1111-4111-8111-000000004105
                        answer_path: /items/1/response
                        section: Outdoor equipment
                        label: Equipment operates normally?
                        type: YES_NO
                        required: true
                        helper_text: null
                        value: 'No'
                        photo_requirement: NONE
                        attached_photo_url: null
                      - question_id: null
                        answer_path: /items/2/left/0/response
                        section: Outdoor equipment
                        label: Condition
                        type: PASS_FAIL_FLAG
                        required: true
                        helper_text: null
                        value: Flag
                        photo_requirement: OPTIONAL
                        attached_photo_url: https://example.invalid/inspection-photo.png
                      - question_id: null
                        answer_path: /items/2/right/0/response
                        section: Outdoor equipment
                        label: Notes
                        type: TEXT
                        required: true
                        helper_text: Explain the finding
                        value: null
                        photo_requirement: NONE
                        attached_photo_url: null
                pagination:
                  next_cursor: null
                meta:
                  request_id: 11111111-1111-4111-8111-000000009999
                  generated_at: '2026-09-08T19:00:00Z'
                  timezone: America/Los_Angeles
        '400':
          description: >-
            Malformed input, unknown query parameter, unsupported combination or
            invalid cursor.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INVALID_REQUEST
                  message: end_date must be later than start_date
                  request_id: example-request
                  details: []
        '401':
          description: Missing, invalid or expired key, or invalid linked identity.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            WWW-Authenticate:
              schema:
                type: string
              example: Bearer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHENTICATED
                  message: A valid API key is required
                  request_id: example-request
                  details: []
        '404':
          description: >-
            Missing resource or resource outside the authenticated company. Same
            response for both.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found
                  request_id: example-request
                  details: []
        '405':
          description: Write methods do not mutate business data and return 405.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            Allow:
              schema:
                type: string
              example: GET, HEAD, OPTIONS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: METHOD_NOT_ALLOWED
                  message: This resource supports GET
                  request_id: example-request
                  details: []
        '429':
          description: Company request budget exhausted; retry after the indicated delay.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
            Retry-After:
              schema:
                type: integer
                minimum: 1
              description: Seconds before retrying.
              example: 30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: RATE_LIMITED
                  message: Request limit exceeded
                  request_id: example-request
                  details: []
        '500':
          description: >-
            Unexpected failure. Share request_id with support; no stack or
            provider secrets in response.
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INTERNAL_ERROR
                  message: Unable to complete request
                  request_id: example-request
                  details: []
      security:
        - apiKey: []
components:
  schemas:
    FormResponsePage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FormResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - data
        - pagination
        - meta
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - INVALID_CURSOR
                - UNAUTHENTICATED
                - NOT_FOUND
                - METHOD_NOT_ALLOWED
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
            request_id:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - field
                  - message
          required:
            - code
            - message
            - request_id
            - details
      required:
        - error
    FormResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        form_id:
          type: string
          format: uuid
          description: >-
            Owned source template ID for grouping; current template content is
            not used to interpret this response.
        name:
          type: string
          nullable: true
          description: Captured form name, not the current template name.
        instance_number:
          type: integer
          description: >-
            Recorded instance number, normally a positive ordinal within its
            appointment and form.
        label:
          type: string
          nullable: true
        ad_hoc:
          type: boolean
        appointment_id:
          type: string
          format: uuid
        job_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        location_id:
          type: string
          nullable: true
          format: uuid
        last_edited_by:
          allOf:
            - $ref: '#/components/schemas/NullableReference'
            - description: >-
                Recorded last saver, not necessarily the person who answered or
                completed the form.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          description: >-
            Last instance save; saving other forms in the same editor can also
            advance it. Not an answer-change or completion timestamp.
        completed:
          type: boolean
          nullable: true
          description: >-
            Existing required-answer and required-photo check on captured
            content. Empty or optional-only forms can be complete. Null when the
            captured structure cannot be interpreted; not a submission or
            signature verification state.
        questions:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/FormResponseQuestion'
          description: >-
            Complete captured inputs in display order, including unanswered
            inputs and both columns. Null when any captured structure is
            unsupported or malformed; no partial question list is returned.
      required:
        - id
        - form_id
        - name
        - instance_number
        - label
        - ad_hoc
        - appointment_id
        - job_id
        - account_id
        - location_id
        - last_edited_by
        - created_at
        - updated_at
        - completed
        - questions
    Pagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
          description: >-
            Opaque continuation. Null ends traversal. Keep the same filters;
            page size may change.
      required:
        - next_cursor
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
        generated_at:
          type: string
          format: date-time
        timezone:
          type: string
      required:
        - request_id
        - generated_at
        - timezone
      description: >-
        Generation time and company timezone. generated_at is not a snapshot or
        synchronization token.
    NullableReference:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
      required:
        - id
        - name
    FormResponseQuestion:
      type: object
      properties:
        question_id:
          type: string
          nullable: true
          format: uuid
          description: >-
            Persisted captured question ID when present; not a guaranteed
            identity across template revisions.
        answer_path:
          type: string
          description: >-
            Instance-local JSON pointer into captured content, such as
            /items/2/left/0/response. Reordering captured questions changes this
            path.
        section:
          type: string
          nullable: true
          description: Nearest preceding captured section title, if present.
        label:
          type: string
        type:
          type: string
          enum:
            - CHECKBOX
            - TEXT
            - PASS_FAIL_FLAG
            - YES_NO
            - INPUT
            - SIGNATURE
            - PHOTO
        required:
          type: boolean
        helper_text:
          type: string
          nullable: true
        value:
          type: string
          nullable: true
          description: >-
            Recorded string, or null when absent. No, false, 0, and empty
            strings remain distinct. TEXT HTML is converted to plain text. PHOTO
            normally stores a CDN URL; SIGNATURE normally stores a PNG data URI.
            Media strings are not verified attachment references.
        photo_requirement:
          type: string
          enum:
            - NONE
            - OPTIONAL
            - REQUIRED
        attached_photo_url:
          type: string
          nullable: true
          description: >-
            Recorded associated-photo string; no media is fetched or signed by
            this API.
      required:
        - question_id
        - answer_path
        - section
        - label
        - type
        - required
        - helper_text
        - value
        - photo_requirement
        - attached_photo_url
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Existing Breezy API key. Grants all published reads in its associated
        company. No app permission scopes.

````