openapi: 3.0.3
info:
  title: Form.taxi Form API
  description: >
    API for retrieving form submissions via Form.taxi.
    Available from the "Standard" plan and above.
    Further information: https://docs.form.taxi/en/api
  version: 1.0.0
  contact:
    url: https://form.taxi

servers:
  - url: https://form.taxi/api/v1

paths:
  /form/submissions/{form_code}:
    get:
      summary: Retrieve submissions
      description: >
        Returns the list of form submissions including all field values for the
        specified form. The `Api-Key` header must be sent with every request
        and is specific to each form.
      operationId: getSubmissions
      parameters:
        - name: form_code
          in: path
          required: true
          description: >
            The unique code of the form. Found in the connection details
            of the form overview in the panel.
          schema:
            type: string
            example: cp2j57ye

        - name: since
          in: query
          required: false
          description: >
            Filters the submission list to a specific start date.
            Must be provided in ISO 8601 format.
          schema:
            type: string
            format: date-time
            example: "2025-08-13T13:15:50+02:00"

        - name: limit
          in: query
          required: false
          description: >
            Limits the number of submissions returned.
            Default: 25, Maximum: 50.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 25
            example: 10

        - name: page
          in: query
          required: false
          description: >
            Specifies which page of the submission list to return.
            Default: 1.
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 2

        - name: spam
          in: query
          required: false
          description: >
            By default, only inbox submissions are returned.
            Set `spam=true` to also include submissions from the spam folder.
          schema:
            type: boolean
            default: false
            example: true

        - name: attachments
          in: query
          required: false
          description: >
            Submission data is returned with file attachments by default.
            Set `attachments=false` to exclude file attachments from the response.
          schema:
            type: boolean
            default: true
            example: false

      security:
        - ApiKeyHeader: []

      responses:
        "200":
          description: Submissions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubmissionsResponse"
              example:
                success: true
                data:
                  pagination:
                    countTotal: 54
                    countPage: 25
                    currentPage: 1
                    totalPages: 2
                  form:
                    code: cp2j57ye
                    title: Contact Form
                    url: https://domain.com
                  submissions:
                    - _id: rIYOyM9pUebOq1kwvoz6M0JcXhhVsuuK
                      _date: "2024-08-21T11:59:32+02:00"
                      _box: inbox
                      _url: https://form.taxi/panel/form/submission/rIYOyM9pUebOq1kwvoz6M0JcXhhVsuuK
                      fields:
                        Email: email@domain.com
                        Message: This is my message.
                      fields_summary:
                        text: "EMAIL: email@domain.com, MESSAGE: This is my message."
                        html: "<b>Email</b>: email@domain.com, <b>Message</b>: This is my message."
                        markdown: "*Email*: email@domain.com, *Message*: This is my message."
                      attachments:
                        - fieldName: Image
                          fileName: Photo.jpg
                          fileSize: "896641"
                          url: https://form.taxi/download/pPzaimJfruButrcB/Photo.jpg

        "401":
          description: API key invalid or missing.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error: api_key_invalid

        "404":
          description: Form not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error: unknown_form

        "426":
          description: Access not allowed (e.g. current plan does not include API access).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error: access_not_allowed

components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Api-Key
      description: >
        Form-specific API key. Found in the connection details
        of the form overview in the panel under "Connection Data".

  schemas:
    SubmissionsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            pagination:
              $ref: "#/components/schemas/Pagination"
            form:
              $ref: "#/components/schemas/FormInfo"
            submissions:
              type: array
              items:
                $ref: "#/components/schemas/Submission"

    Pagination:
      type: object
      properties:
        countTotal:
          type: integer
          description: Total number of submissions.
          example: 54
        countPage:
          type: integer
          description: Number of submissions on the current page.
          example: 25
        currentPage:
          type: integer
          description: Current page number.
          example: 1
        totalPages:
          type: integer
          description: Total number of pages.
          example: 2

    FormInfo:
      type: object
      properties:
        code:
          type: string
          description: Form code.
          example: cp2j57ye
        title:
          type: string
          description: Title of the form.
          example: Contact Form
        url:
          type: string
          format: uri
          description: URL of the page where the form is embedded.
          example: https://domain.com

    Submission:
      type: object
      properties:
        _id:
          type: string
          description: Unique ID of the submission.
          example: rIYOyM9pUebOq1kwvoz6M0JcXhhVsuuK
        _date:
          type: string
          format: date-time
          description: Date and time of the submission (ISO 8601).
          example: "2024-08-21T11:59:32+02:00"
        _box:
          type: string
          description: Folder the submission is stored in (inbox or spam).
          enum:
            - inbox
            - spam
          example: inbox
        _url:
          type: string
          format: uri
          description: URL of the submission in the Form.taxi panel.
          example: https://form.taxi/panel/form/submission/rIYOyM9pUebOq1kwvoz6M0JcXhhVsuuK
        fields:
          type: object
          description: >
            Form fields as key-value pairs. Keys correspond to the
            field names of the form.
          additionalProperties:
            type: string
          example:
            Email: email@domain.com
            Nachricht: This is my message.
        fields_summary:
          $ref: "#/components/schemas/FieldsSummary"
        attachments:
          type: array
          description: List of file attachments for this submission.
          items:
            $ref: "#/components/schemas/Attachment"

    FieldsSummary:
      type: object
      description: Summary of the form fields in various formats.
      properties:
        text:
          type: string
          description: Fields as plain text.
          example: "EMAIL: email@domain.com, MESSAGE: This is my message."
        html:
          type: string
          description: Fields as HTML.
          example: "<b>Email</b>: email@domain.com, <b>Message</b>: This is my message."
        markdown:
          type: string
          description: Fields as Markdown.
          example: "*Email*: email@domain.com, *Message*: This is my message."

    Attachment:
      type: object
      description: File attachment of a submission.
      properties:
        fieldName:
          type: string
          description: Name of the upload field in the form.
          example: Image
        fileName:
          type: string
          description: Original file name.
          example: Photo.jpg
        fileSize:
          type: string
          description: File size in bytes (as string).
          example: "896641"
        url:
          type: string
          format: uri
          description: Download URL of the file.
          example: https://form.taxi/download/pPzaimJfruButrcB/Photo.jpg

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Error code.
          enum:
            - unknown_form
            - api_key_invalid
            - access_not_allowed
          example: api_key_invalid