openapi: 3.0.1
info:
  description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
  title: Samsara Forms API
  version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Forms
paths:
  /preview/form-templates:
    get:
      description: "Returns a list of the organization's form templates.\n\n <b>Rate limit:</b> 5 requests/sec (learn more about rate limits <a href=\"https://developers.samsara.com/docs/rate-limits\" target=\"_blank\">here</a>).\n\nTo use this endpoint, select **Read Preview** under the  category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>\n\nEndpoints in this section are in Preview. These APIs are not functional and are instead for soliciting feedback from our API users on the intended design of this API. Additionally, it is not guaranteed that we will be releasing an endpoint included in this section to production. This means that developers should **NOT** rely on these APIs to build business critical applications\n\n- Samsara may change the structure of a preview API's interface without versioning or any notice to API users.\n\n- When an endpoint becomes generally available, it will be announced in the API [changelog](https://developers.samsara.com/changelog).\n \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team."
      operationId: getFormTemplates
      parameters:
      - description: A comma-separated list containing up to 100 template IDs to filter on.
        explode: false
        in: query
        name: ids
        schema:
          items:
            type: string
          type: array
        style: form
      - description: ' If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.'
        in: query
        name: after
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesResponseBody'
          description: OK response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesUnauthorizedErrorResponseBody'
          description: Unauthorized response.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesNotFoundErrorResponseBody'
          description: Not Found response.
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesMethodNotAllowedErrorResponseBody'
          description: Method Not Allowed response.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesTooManyRequestsErrorResponseBody'
          description: Too Many Requests response.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesInternalServerErrorResponseBody'
          description: Internal Server Error response.
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesNotImplementedErrorResponseBody'
          description: Not Implemented response.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesBadGatewayErrorResponseBody'
          description: Bad Gateway response.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesServiceUnavailableErrorResponseBody'
          description: Service Unavailable response.
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesGatewayTimeoutErrorResponseBody'
          description: Gateway Timeout response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplatesGetFormTemplatesBadRequestErrorResponseBody'
          description: Bad Request response.
      summary: '[preview] Get a List of Form Templates.'
      tags:
      - Forms
components:
  schemas:
    FormTemplatesGetFormTemplatesNotImplementedErrorResponseBody:
      description: Requested endpoint is not yet implemented
      properties:
        message:
          description: Message of error
          example: Not implemented.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormTemplateSectionObjectResponseBody:
      description: Form Template section object.
      properties:
        fieldIndexFirstInclusive:
          description: The index of the first field from the fields array that is in this section. Index 0 represents the first field definition of the fields array.
          example: 0
          format: int64
          type: integer
        fieldIndexLastInclusive:
          description: The index of the last field from the fields array that is in this section.
          example: 9
          format: int64
          type: integer
        label:
          description: Label of the section.
          example: Engine Hours
          type: string
      required:
      - fieldIndexFirstInclusive
      - fieldIndexLastInclusive
      - label
      type: object
    FormTemplateResponseObjectResponseBody:
      description: Form Template response object.
      properties:
        approvalConfig:
          $ref: '#/components/schemas/FormsApprovalConfigObjectResponseBody'
        createdAtTime:
          description: Creation time of the form template. UTC timestamp in RFC 3339 format.
          example: '2019-06-13T19:08:25Z'
          format: date-time
          type: string
        createdBy:
          $ref: '#/components/schemas/FormsPolymorphicUserObjectResponseBody'
        description:
          description: Description of the form template.
          example: This is a form template for job J999.
          type: string
        fields:
          description: List of fields in the form template.
          items:
            $ref: '#/components/schemas/FormsFieldDefinitionObjectResponseBody'
          type: array
        id:
          description: Unique identifier of the form template.
          example: 9814a1fa-f0c6-408b-bf85-51dc3bc71ac7
          format: uuid
          type: string
        revisionId:
          description: Unique identifier of the form template revision.
          example: 1214a1fa-f0c6-408b-bf85-51dc3bc71ac7
          format: uuid
          type: string
        sections:
          description: List of sections in the form template.
          items:
            $ref: '#/components/schemas/FormTemplateSectionObjectResponseBody'
          type: array
        title:
          description: Title of the form template.
          example: Job - J999
          type: string
        updatedAtTime:
          description: Update time of the form template. UTC timestamp in RFC 3339 format.
          example: '2019-06-13T19:08:25Z'
          format: date-time
          type: string
        updatedBy:
          $ref: '#/components/schemas/FormsPolymorphicUserObjectResponseBody'
      required:
      - createdAtTime
      - createdBy
      - description
      - fields
      - id
      - revisionId
      - sections
      - title
      - updatedAtTime
      - updatedBy
      type: object
    FormTemplatesGetFormTemplatesUnauthorizedErrorResponseBody:
      description: Unauthorized
      properties:
        message:
          description: Message of error
          example: Invalid token.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormsFieldDefinitionObjectResponseBody:
      description: Forms field definition object.
      properties:
        allowManualEntry:
          description: Indicates whether the field allows manual entry of a person. Only present for person fields.
          example: true
          type: boolean
        allowedAssetTypes:
          description: List of allowed asset types that can be selected for this field. Only present for asset fields.
          example:
          - Vehicle
          - Trailer
          items:
            description: '  Valid values: `Vehicle`, `Trailer`, `Equipment`, `UnpoweredAsset`'
            enum:
            - Vehicle
            - Trailer
            - Equipment
            - UnpoweredAsset
            example: Vehicle
            type: string
          type: array
        allowedDateTimeValueType:
          description: 'Type of date/time entry allowed for this question. Only present for datetime fields.  Valid values: `datetime`, `date`, `time`'
          enum:
          - datetime
          - date
          - time
          example: datetime
          type: string
        filterByCurrentDriverTags:
          description: Indicates whether the person search filters by the current logged in worker's tags. Only present for person fields.
          example: true
          type: boolean
        filterByRoleIds:
          description: List of role IDs to filter org users by, representing which roles are selectable people for this field. Only present for person fields.
          example:
          - 23d4d8d3-dc10-4e7a-a183-69968751f23e
          items:
            example: Natus aspernatur est est qui quae.
            type: string
          type: array
        id:
          description: Identifier of the field.
          example: 9814a1fa-f0c6-408b-bf85-51dc3bc71ac7
          format: uuid
          type: string
        includeDrivers:
          description: Indicates whether the field includes drivers as selectable people. Only present for person fields.
          example: true
          type: boolean
        includeUsers:
          description: Indicates whether the field includes users as selectable people. Only present for person fields.
          example: true
          type: boolean
        isRequired:
          description: Indicates whether the form field is required to be filled out by the user.
          example: true
          type: boolean
        label:
          description: Label of the field.
          example: Engine Hours
          type: string
        legalText:
          description: Legal text for the field. Only present for signature fields.
          example: I consent to using electronic signatures in this transaction.
          type: string
        numDecimalPlaces:
          description: Number of decimal places allowed. Only present for number fields.
          example: 2
          format: int64
          type: integer
        options:
          description: List of select options for checkboxes or multiple choice fields.
          items:
            $ref: '#/components/schemas/FormsSelectOptionObjectResponseBody'
          type: array
        questionWeight:
          description: The maximum possible score weight for this field. For multiple choice fields, this number is the highest option score weight of the given options. For checkboxes fields, this number is the sum of the score weights for all scored options. Only present for multiple choice or checkboxes fields that have scoring.
          example: 5
          format: int64
          type: integer
        type:
          description: 'Type of the field.  Valid values: `number`, `text`, `multiple_choice`, `check_boxes`, `media`, `datetime`, `signature`, `asset`, `person`, `geofence`, `instruction`, `media_instruction`'
          enum:
          - number
          - text
          - multiple_choice
          - check_boxes
          - media
          - datetime
          - signature
          - asset
          - person
          - geofence
          - instruction
          - media_instruction
          example: number
          type: string
      required:
      - id
      - isRequired
      - label
      - type
      type: object
    FormsPolymorphicUserObjectResponseBody:
      description: User or driver object.
      properties:
        id:
          description: ID of the polymorphic user.
          example: '938172'
          type: string
        type:
          description: 'The type of the polymorphic user.  Valid values: `driver`, `user`'
          enum:
          - driver
          - user
          example: driver
          type: string
      required:
      - id
      - type
      type: object
    FormTemplatesGetFormTemplatesNotFoundErrorResponseBody:
      description: Resource not found
      properties:
        message:
          description: Message of error
          example: Object not found.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    GoaPaginationResponseResponseBody:
      description: Pagination parameters.
      properties:
        endCursor:
          description: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.
          example: MjkY
          type: string
        hasNextPage:
          description: True if there are more pages of results immediately available after this endCursor.
          example: true
          type: boolean
      required:
      - endCursor
      - hasNextPage
      type: object
    FormsSingleApprovalConfigObjectResponseBody:
      description: Single approval configuration object.
      properties:
        allowManualApproverSelection:
          description: Indicates whether approver can be manually selected. True by default.
          example: true
          type: boolean
        requirements:
          $ref: '#/components/schemas/SingleApprovalRequirementsObjectResponseBody'
      required:
      - allowManualApproverSelection
      - requirements
      type: object
    FormTemplatesGetFormTemplatesGatewayTimeoutErrorResponseBody:
      description: Gateway timeout
      properties:
        message:
          description: Message of error
          example: context deadline exceeded
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormTemplatesGetFormTemplatesResponseBody:
      properties:
        data:
          description: List of form templates.
          items:
            $ref: '#/components/schemas/FormTemplateResponseObjectResponseBody'
          type: array
        pagination:
          $ref: '#/components/schemas/GoaPaginationResponseResponseBody'
      required:
      - data
      - pagination
      type: object
    SingleApprovalRequirementsObjectResponseBody:
      description: Single approval requirements object.
      properties:
        roleIds:
          description: List of role IDs representing which user roles can be approvers.
          example:
          - 23d4d8d3-dc10-4e7a-a183-69968751f23e
          items:
            example: Minus temporibus fugit.
            type: string
          type: array
      required:
      - roleIds
      type: object
    FormsSelectOptionObjectResponseBody:
      description: Multiple choice or checkbox value option object.
      properties:
        id:
          description: Identifier of the option.
          example: e879028d-bce5-0238-ffec-11cd9236bcda
          type: string
        ignoreQuestionFromScoreIfSelected:
          description: Indicates whether the question should be ignored from the total score if this option is selected. Returns true if a score weight was not given to this option. Only present when the select form field has scoring.
          example: false
          type: boolean
        label:
          description: Label of the option.
          example: 'Yes'
          type: string
        optionScoreWeight:
          description: Score weight of the option, indicates number of score points received if this option is selected. Only present if the select form field has scoring.
          example: 5
          format: int64
          type: integer
      required:
      - id
      - label
      type: object
    FormTemplatesGetFormTemplatesMethodNotAllowedErrorResponseBody:
      description: Method not allowed
      properties:
        message:
          description: Message of error
          example: DELETE not allowed on /endpoint.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormTemplatesGetFormTemplatesBadRequestErrorResponseBody:
      description: Bad Request parameters
      properties:
        message:
          description: Message of error
          example: Invalid value for parameter.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormTemplatesGetFormTemplatesBadGatewayErrorResponseBody:
      description: Bad Gateway
      properties:
        message:
          description: Message of error
          example: 'rpc error: code = Unknown desc = connection refused'
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormTemplatesGetFormTemplatesServiceUnavailableErrorResponseBody:
      description: Service unavailable
      properties:
        message:
          description: Message of error
          example: context deadline exceeded
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormsApprovalConfigObjectResponseBody:
      description: Form Template approval configuration object.
      properties:
        singleApprovalConfig:
          $ref: '#/components/schemas/FormsSingleApprovalConfigObjectResponseBody'
        type:
          description: 'Type of approval.  Valid values: `singleApproval`'
          enum:
          - singleApproval
          example: singleApproval
          type: string
      required:
      - type
      type: object
    FormTemplatesGetFormTemplatesInternalServerErrorResponseBody:
      description: An internal server error occurred
      properties:
        message:
          description: Message of error
          example: Failed to execute GraphQL query.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
    FormTemplatesGetFormTemplatesTooManyRequestsErrorResponseBody:
      description: Too many requests
      properties:
        message:
          description: Message of error
          example: Exceeded rate limit.
          type: string
        requestId:
          description: The request ID; used when reaching out to support for issues with requests.
          example: 8916e1c1
          type: string
      required:
      - message
      - requestId
      type: object
  securitySchemes:
    AccessTokenHeader:
      type: http
      scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
  explorer-enabled: true
  proxy-enabled: true