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

# List form submissions

> Returns a paginated list of submissions for a form. Each submission's `form_data` field is a JSON-encoded string of the respondent's answers.




## OpenAPI

````yaml openapi-forms GET /api/forms/{form_id}/submissions
openapi: 3.0.0
info:
  title: Paubox Forms API
  description: >
    The Paubox Forms API has two kinds of endpoints. Public, respondent-facing
    endpoints (retrieving a form definition for rendering and submitting a form
    response) require no authentication. Authenticated management endpoints
    (creating, listing, updating, copying, archiving forms, and reading or
    exporting submissions) require a Paubox API key with the "forms" scope, sent
    as `Authorization: Bearer YOUR_API_KEY`. API keys are generated in the
    Paubox dashboard.
  version: 1.0.0
servers:
  - url: https://api.paubox.com/v1/forms
    description: Paubox Forms API
security: []
tags:
  - name: Forms
    description: Retrieve form definitions and accept submissions
  - name: Form management
    description: Create, list, update, copy, and archive forms (requires API key)
  - name: Submissions
    description: List and export form submissions (requires API key)
paths:
  /api/forms/{form_id}/submissions:
    get:
      tags:
        - Submissions
      summary: List form submissions
      description: >
        Returns a paginated list of submissions for a form. Each submission's
        `form_data` field is a JSON-encoded string of the respondent's answers.
      operationId: listFormSubmissions
      parameters:
        - name: form_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: UUID of the form
        - name: submission_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter the results to a single submission by its UUID.
        - name: order_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - created_at
              - submitter_email
            default: created_at
          description: Field to order results by.
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort direction.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: Page number to return.
        - name: items
          in: query
          required: false
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Number of submissions per page (maximum 100).
      responses:
        '200':
          description: Paginated list of submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSubmissionListResponse'
              examples:
                example:
                  summary: Example response
                  value:
                    data:
                      - id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                        form_id: 550e8400-e29b-41d4-a716-446655440000
                        form_data: >-
                          {"first_name":"Jane","last_name":"Smith","email":"jane@example.com"}
                        storage_type: S3
                        storage_url: null
                        submitter_email: jane@example.com
                        recipients: intake@example.com
                        attachment_name: null
                        attachment_url: null
                        attachment_type: null
                        attachment: null
                        created_at: '2024-06-05T14:22:00Z'
                    total: 42
                    page: 1
                    items: 50
        '401':
          description: Missing or invalid API key, or the key lacks the "forms" scope
        '403':
          description: The form belongs to a different customer
        '404':
          description: Form not found
      security:
        - bearerAuth: []
components:
  schemas:
    FormSubmissionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FormSubmission'
        total:
          type: integer
          description: Total number of matching submissions
        page:
          type: integer
          description: Current page number
        items:
          type: integer
          description: Number of items per page
    FormSubmission:
      type: object
      properties:
        id:
          type: string
          format: uuid
        form_id:
          type: string
          format: uuid
        form_data:
          type: string
          description: |
            JSON-encoded object of the respondent's answers.
        storage_type:
          type: string
        storage_url:
          type: string
          nullable: true
        submitter_email:
          type: string
          nullable: true
        recipients:
          type: string
          nullable: true
        attachment_name:
          type: string
          nullable: true
        attachment_url:
          type: string
          nullable: true
        attachment_type:
          type: string
          nullable: true
        attachment:
          nullable: true
        created_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Paubox API key sent as `Authorization: Bearer YOUR_API_KEY`. API keys
        are created in the Paubox dashboard and must have the "forms" scope; a
        key without the forms scope receives 401 Unauthorized. A valid key used
        against a resource that belongs to a different customer receives 403
        Forbidden.

````