openapi: 3.1.0
info:
  title: Fieldwire Forms API
  description: |
    Build account-level form templates (sections, inputs, custom data types,
    statuses, permissions) and capture form records (with section records,
    values, signatures, and markups) in the field. Powers Fieldwire's daily
    reports, safety inspections, QA/QC checklists, and any custom data
    collection workflow.
  version: v3.1
  contact:
    name: Fieldwire Developer Support
    url: https://developers.fieldwire.com/
  license:
    name: Fieldwire Terms of Service
    url: https://www.fieldwire.com/terms/
servers:
  - url: https://client-api.us.fieldwire.com/api/v3
    description: US Region (project-scoped form records)
  - url: https://client-api.eu.fieldwire.com/api/v3
    description: EU Region (project-scoped form records)
  - url: https://client-api.super.fieldwire.com
    description: Super Host (account-level form templates)
security:
  - BearerAuth: []
tags:
  - name: Form Templates
    description: Account-level form template definitions, publication, and transfer.
  - name: Form Sections
    description: Section structure within a form template.
  - name: Form Inputs
    description: Inputs (text, number, photo, signature, choice, etc.) inside a section.
  - name: Form Records
    description: Captured form responses per project.
paths:
  /account/form_templates/{form_template_id}/sections:
    get:
      operationId: getFormTemplateSections
      summary: Get Form Template Sections
      tags: [Form Sections]
      parameters:
        - $ref: '#/components/parameters/FormTemplateId'
      responses:
        '200':
          description: Section list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormTemplateSection'
    post:
      operationId: createFormTemplateSection
      summary: Create Form Template Section
      tags: [Form Sections]
      parameters:
        - $ref: '#/components/parameters/FormTemplateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormTemplateSection'
      responses:
        '201':
          description: Created section.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplateSection'
  /account/form_templates/{form_template_id}/sections/{section_id}/inputs:
    get:
      operationId: getFormTemplateSectionInputs
      summary: Get Form Template Section Inputs
      tags: [Form Inputs]
      parameters:
        - $ref: '#/components/parameters/FormTemplateId'
        - $ref: '#/components/parameters/SectionId'
      responses:
        '200':
          description: Input list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormTemplateInput'
    post:
      operationId: createFormTemplateSectionInput
      summary: Create Form Template Section Input
      tags: [Form Inputs]
      parameters:
        - $ref: '#/components/parameters/FormTemplateId'
        - $ref: '#/components/parameters/SectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormTemplateInput'
      responses:
        '201':
          description: Created input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplateInput'
  /projects/{project_id}/forms:
    get:
      operationId: getFormsInProject
      summary: Get Forms In Project
      tags: [Form Records]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: Form record list.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormRecord'
    post:
      operationId: createFormInProject
      summary: Create Form In Project
      tags: [Form Records]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormRecordCreate'
      responses:
        '201':
          description: Created form record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormRecord'
  /projects/{project_id}/forms/{form_id}:
    get:
      operationId: getFormById
      summary: Get Form By ID
      description: Returns the form record with all section records, values, and signatures.
      tags: [Form Records]
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/FormId'
      responses:
        '200':
          description: Form record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormRecordFull'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
    FormTemplateId:
      name: form_template_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
    SectionId:
      name: section_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
    FormId:
      name: form_id
      in: path
      required: true
      schema:
        type: integer
        format: int64
  schemas:
    FormTemplateSection:
      type: object
      properties:
        id:
          type: integer
          format: int64
        form_template_id:
          type: integer
          format: int64
        name:
          type: string
        position:
          type: number
          format: double
        is_repeatable:
          type: boolean
    FormTemplateInput:
      type: object
      properties:
        id:
          type: integer
          format: int64
        section_id:
          type: integer
          format: int64
        name:
          type: string
        kind:
          type: string
          enum: [text, number, boolean, choice, multi_choice, date, time, datetime, photo, signature, attachment]
        is_required:
          type: boolean
        data_type_id:
          type: integer
          format: int64
        position:
          type: number
          format: double
    FormRecord:
      type: object
      properties:
        id:
          type: integer
          format: int64
        project_id:
          type: integer
          format: int64
        form_template_id:
          type: integer
          format: int64
        name:
          type: string
        status:
          type: string
          enum: [draft, in_review, approved, rejected]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    FormRecordCreate:
      type: object
      required: [form_template_id]
      properties:
        form_template_id:
          type: integer
          format: int64
        name:
          type: string
    FormRecordFull:
      allOf:
        - $ref: '#/components/schemas/FormRecord'
        - type: object
          properties:
            section_records:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  section_id:
                    type: integer
                    format: int64
                  values:
                    type: array
                    items:
                      type: object
                      properties:
                        input_id:
                          type: integer
                          format: int64
                        value:
                          description: Input value (type depends on input kind).
                          oneOf:
                            - type: string
                            - type: number
                            - type: boolean
                            - type: array
                              items:
                                type: string