openapi: 3.2.0
info:
  version: 1.0.0
  title: Paperform Form Fields API
  contact:
    name: Paperform API Support
    url: https://paperform.co
    email: support@paperform.co
servers:
- url: https://api.paperform.co/v1
security:
- bearerAuth: []
tags:
- name: Form Fields
paths:
  /forms/{slug_or_id}/fields:
    get:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      - $ref: '#/components/parameters/fieldSearch'
      description: This endpoint returns the list of fields available for a specific form by slug or ID. This feature is available as part of the Standard API.
      operationId: listFormFields
      tags:
      - Form Fields
      responses:
        '200':
          description: 'Successfully returned fields for a single form that matched the provided slug or ID

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  results:
                    type: object
                    properties:
                      fields:
                        type: array
                        items:
                          $ref: '#/components/schemas/FormFieldCollectionItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: List form fields
      x-summary-source: derived
  /forms/{slug_or_id}/fields/{field_key}:
    get:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      - $ref: '#/components/parameters/fieldKey'
      description: 'This endpoint returns a fields for a specific form by field key.

        This feature is available as part of the Standard API.'
      operationId: getFormField
      tags:
      - Form Fields
      responses:
        '200':
          description: 'Successfully returned a field for a single form that matched the provided field key.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  results:
                    type: object
                    properties:
                      field:
                        type: object
                        oneOf:
                        - $ref: '#/components/schemas/Field'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Get form field
      x-summary-source: derived
    put:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      - $ref: '#/components/parameters/fieldKey'
      description: 'This endpoint updates a field on a form.

        This feature is available as part of the Standard API.'
      operationId: updateFormField
      tags:
      - Form Fields
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Field'
            examples:
              update-dropdown-options:
                summary: Update the options for a Dropdown field
                value:
                  dropdown:
                    options:
                    - Option 1
                    - Option 2
                    - Option 3
              update-choices-options:
                summary: Update the options for a Choices field
                value:
                  choices:
                    options:
                    - Option 1
                    - Option 2
                    - Option 3
              update-scale-options:
                summary: Update the options for a Scale field
                value:
                  scale:
                    options:
                    - Option 1
                    - Option 2
                    - Option 3
              update-rank-options:
                summary: Update the options for a Rank field
                value:
                  rank:
                    options:
                    - Option 1
                    - Option 2
                    - Option 3
              update-calculations:
                summary: Update the calculation for a Calculations field
                value:
                  calculations:
                    calculation: 1 + 2
              update-products:
                summary: Update the products for a Products field
                value:
                  products:
                    products:
                    - SKU: PRODUCT-1
                      name: Product 1
                      price: 1
                      images:
                      - url: https://example.com/image1.jpg
                        width: 100
                        height: 100
      responses:
        '200':
          description: 'Successfully updated a field with the provided values

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  results:
                    type: object
                    properties:
                      field:
                        $ref: '#/components/schemas/Field'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Validation'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Update form field
      x-summary-source: derived
components:
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - not_found
                  description: The requested resource was not found.
    Throttled:
      description: Too Many Requests
      content:
        text/html:
          schema:
            type: string
            enum:
            - Too many requests.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - authentication
                  description: Token not provided for not valid.
    BadRequest:
      description: Invalid Request
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - validation
                  description: Invalid parameters provided.
    Forbidden:
      description: Not Permitted
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - permission
                  description: Not permitted to access requested resource.
    Validation:
      description: Validation Error
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - validation
                  description: Invalid parameters provided.
    Unexpected:
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - server_error
                  description: An unexpected error.
  schemas:
    matrix:
      type: object
      description: Matrix field type.
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: matrix
            readOnly: true
            description: The type of field (Matrix).
            enum:
            - matrix
          matrix:
            type: object
            properties:
              rows:
                type: array
                description: The labels for the matrix rows. Maximum 50 rows, each label up to 50 characters.
                maxItems: 50
                example:
                - Row 1
                - Row 2
                - Row 3
                items:
                  type: string
                  maxLength: 50
              columns:
                type: array
                description: The labels for the matrix columns. Maximum 50 columns, each label up to 50 characters.
                maxItems: 50
                example:
                - Column 1
                - Column 2
                - Column 3
                items:
                  type: string
                  maxLength: 50
    color:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: color
            readOnly: true
            description: The type of field (Color Picker).
            enum:
            - color
    appointment:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: appointment
            readOnly: true
            description: The type of field (Appointment).
            enum:
            - appointment
    FormFieldStandardProperties:
      type: object
      description: Other type of form field.
      properties:
        key:
          type: string
          example: 3jbh8
          readOnly: true
          description: The unique key for this field.
        title:
          type:
          - string
          - 'null'
          description: The title of this field.
        description:
          type:
          - string
          - 'null'
          description: The description of this field.
        required:
          type:
          - boolean
          - 'null'
          example: true
          description: Whether this field is required.
        custom_key:
          type:
          - string
          - 'null'
          description: The custom key of this field.
        placeholder:
          type:
          - string
          - 'null'
          description: The placeholder for this field.
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
          example: error
        message:
          type: string
          description: An error message.
          example: Invalid request
        details:
          type: array
          description: Suggested actions to resolve the error.
          items:
            type: string
    address:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: address
            readOnly: true
            description: The type of field (Address).
            enum:
            - address
    country:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: country
            readOnly: true
            description: The type of field (Country).
            enum:
            - country
    subscriptions:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: subscriptions
            readOnly: true
            description: The type of field (Subscriptions).
            enum:
            - subscriptions
    phone:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: phone
            readOnly: true
            description: The type of field (Phone Number).
            enum:
            - phone
    FormFieldCollectionItem:
      type: object
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - properties:
          type:
            $ref: '#/components/schemas/FieldType'
    date:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: date
            readOnly: true
            description: The type of field (Date).
            enum:
            - date
    FieldType:
      type: string
      example: text
      description: The type of field.
      readOnly: true
      enum:
      - text
      - email
      - url
      - yesNo
      - color
      - number
      - phone
      - address
      - country
      - appointment
      - date
      - time
      - scale
      - slider
      - choices
      - dropdown
      - image
      - file
      - signature
      - price
      - products
      - subscriptions
      - calculations
      - hidden
      - rank
      - rating
      - matrix
    ProductItem:
      type: object
      allOf:
      - $ref: '#/components/schemas/ProductUpdate'
      - type: object
        properties:
          SKU:
            type: string
            description: Product SKU.
            example: PRODUCT-1
      required:
      - SKU
      - name
      - price
    ProductUpdate:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Product name.
          example: Product 1
        quantity:
          type:
          - number
          - 'null'
          format: int32
          description: Product quantity.
          example: 5
        price:
          type:
          - number
          - 'null'
          format: double
          description: Product price.
          example: 10
        minimum:
          type:
          - number
          - 'null'
          format: int32
          description: Minimum number of products to be selected.
          example: 1
        maximum:
          type:
          - number
          - 'null'
          format: int32
          description: Maximum number of products to be selected.
          example: 10
        discountable:
          type:
          - boolean
          - 'null'
          description: Whether the product can be discounted.
          example: false
        images:
          type: array
          description: List of product images.
          items:
            type: object
            properties:
              url:
                type: string
                description: Image URL.
                example: https://example.com/image.jpg
              width:
                type: number
                format: int32
                description: Image width.
                example: 100
              height:
                type: number
                format: int32
                description: Image height.
                example: 100
            required:
            - url
            - width
    email:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: email
            readOnly: true
            description: The type of field (Email).
            enum:
            - email
    file:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: file
            readOnly: true
            description: The type of field (File).
            enum:
            - file
    image:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: image
            readOnly: true
            description: The type of field (Image).
            enum:
            - image
    calculations:
      type: object
      description: Calculations field type.
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: calculations
            readOnly: true
            description: The type of field (Calculation).
            enum:
            - calculations
          calculations:
            type: object
            properties:
              calculation:
                type: string
                description: The calculation to perform.
                example: 1 + 1
    rank:
      type: object
      description: Rank field type.
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          rank:
            $ref: '#/components/schemas/FieldOptions'
          type:
            type: string
            example: rank
            description: The type of field (Rank).
            readOnly: true
            enum:
            - rank
    signature:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: signature
            readOnly: true
            description: The type of field (Signature).
            enum:
            - signature
    scale:
      type: object
      description: Scale field type.
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          scale:
            $ref: '#/components/schemas/FieldOptions'
          type:
            type: string
            example: scale
            description: The type of field (Scale).
            readOnly: true
            enum:
            - scale
    Field:
      discriminator:
        propertyName: type
      oneOf:
      - $ref: '#/components/schemas/address'
      - $ref: '#/components/schemas/appointment'
      - $ref: '#/components/schemas/calculations'
      - $ref: '#/components/schemas/choices'
      - $ref: '#/components/schemas/color'
      - $ref: '#/components/schemas/country'
      - $ref: '#/components/schemas/date'
      - $ref: '#/components/schemas/dropdown'
      - $ref: '#/components/schemas/email'
      - $ref: '#/components/schemas/file'
      - $ref: '#/components/schemas/hidden'
      - $ref: '#/components/schemas/image'
      - $ref: '#/components/schemas/matrix'
      - $ref: '#/components/schemas/number'
      - $ref: '#/components/schemas/phone'
      - $ref: '#/components/schemas/price'
      - $ref: '#/components/schemas/products'
      - $ref: '#/components/schemas/rank'
      - $ref: '#/components/schemas/rating'
      - $ref: '#/components/schemas/scale'
      - $ref: '#/components/schemas/signature'
      - $ref: '#/components/schemas/slider'
      - $ref: '#/components/schemas/subscriptions'
      - $ref: '#/components/schemas/text'
      - $ref: '#/components/schemas/time'
      - $ref: '#/components/schemas/url'
      - $ref: '#/components/schemas/yesNo'
    time:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: time
            readOnly: true
            description: The type of field (Time).
            enum:
            - time
    slider:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: slider
            readOnly: true
            description: The type of field (Slider).
            enum:
            - slider
    choices:
      type: object
      description: Choices field type.
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          choices:
            $ref: '#/components/schemas/FieldOptions'
          type:
            type: string
            example: choices
            description: The type of field (Multiple Choice).
            readOnly: true
            enum:
            - choices
    hidden:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: hidden
            readOnly: true
            description: The type of field (Hidden).
            enum:
            - hidden
    FieldOptions:
      type: object
      properties:
        options:
          description: A list of options.
          type: array
          example:
          - Option 1
          - Option 2
          - Option 3
          - etc.
          items:
            type: string
    products:
      type: object
      description: Products field type.
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: products
            readOnly: true
            description: The type of field (Product).
            enum:
            - products
          products:
            type: object
            properties:
              products:
                type: array
                description: List of products.
                items:
                  $ref: '#/components/schemas/ProductItem'
    url:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: url
            readOnly: true
            description: The type of field (Url).
            enum:
            - url
    dropdown:
      type: object
      description: Dropdown field type.
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          dropdown:
            $ref: '#/components/schemas/FieldOptions'
          type:
            type: string
            example: dropdown
            readOnly: true
            description: The type of field (Dropdown).
            enum:
            - dropdown
    text:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: text
            readOnly: true
            description: The type of field (Text).
            enum:
            - text
    number:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: number
            readOnly: true
            description: The type of field (Number).
            enum:
            - number
    rating:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: rating
            readOnly: true
            description: The type of field (Rating).
            enum:
            - rating
    price:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: price
            readOnly: true
            description: The type of field (Price).
            enum:
            - price
    yesNo:
      type: object
      description: Other field type
      allOf:
      - $ref: '#/components/schemas/FormFieldStandardProperties'
      - type: object
        properties:
          type:
            type: string
            example: yesNo
            readOnly: true
            description: The type of field (Yes/No).
            enum:
            - yesNo
  parameters:
    fieldKey:
      in: path
      name: field_key
      required: true
      schema:
        type: string
      description: The key of the field on the form.
      example: a1b2c3d4e5
    slugOrID:
      in: path
      name: slug_or_id
      required: true
      schema:
        type: string
      description: The form's slug, custom slug or ID.
      example: my-form-slug
    fieldSearch:
      in: query
      name: search
      schema:
        type: string
      description: Search fields by name.
      example: Name
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-readme:
  explorer-enabled: true
  proxy-enabled: true