openapi: 3.1.0
info:
  title: Fillout REST API
  description: |-
    A REST API for managing forms, submissions, and webhooks in Fillout

    OpenAPI 3.1 spec mirrored from the public Fillout REST API specification at https://fillout.com/help/openapi.json.
  version: 1.0.0
servers:
- url: https://api.fillout.com/v1/api
  description: Fillout REST API base URL
security:
- bearerAuth: []
paths:
  /forms:
    get:
      summary: Get all forms
      description: Returns a list of all your forms
      operationId: getForms
      responses:
        '200':
          description: List of forms
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FormSummary'
  /forms/{formId}:
    get:
      summary: Get form metadata
      description: Given the formId, returns all the questions in that form and other metadata
      operationId: getFormMetadata
      parameters:
      - name: formId
        in: path
        required: true
        schema:
          type: string
        description: The public ID of your form
      responses:
        '200':
          description: Form metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormMetadata'
  /forms/{formId}/submissions:
    get:
      summary: Get all submissions
      description: Returns a list of all submissions for a given form
      operationId: getAllSubmissions
      parameters:
      - name: formId
        in: path
        required: true
        schema:
          type: string
        description: The public identifier of the form
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 150
          default: 50
        description: The maximum number of submissions to retrieve per request
      - name: afterDate
        in: query
        schema:
          type: string
          format: date-time
        description: A date string to filter submissions submitted after this date
      - name: beforeDate
        in: query
        schema:
          type: string
          format: date-time
        description: A date string to filter submissions submitted before this date
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        description: The starting position from which to fetch the submissions
      - name: status
        in: query
        schema:
          type: string
          enum:
          - finished
          - in_progress
        description: |-
          Pass 'in_progress' to get unfinished submissions. By default, only 'finished' submissions are returned
      - name: includeEditLink
        in: query
        schema:
          type: boolean
        description: Pass true to include a link to edit the submission as 'editLink'
      - name: includePreview
        in: query
        schema:
          type: boolean
        description: Pass true to include preview responses
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: Sort order for the submissions
      - name: search
        in: query
        schema:
          type: string
        description: Filter for submissions containing a string of text
      responses:
        '200':
          description: List of submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionsResponse'
    post:
      summary: Create submissions
      description: Create new submissions for a form
      operationId: createSubmissions
      parameters:
      - name: formId
        in: path
        required: true
        schema:
          type: string
        description: The public identifier of the form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubmissionsRequest'
      responses:
        '200':
          description: Created submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubmissionsResponse'
  /forms/{formId}/submissions/{submissionId}:
    get:
      summary: Get submission by ID
      description: Returns a single submission by its ID
      operationId: getSubmissionById
      parameters:
      - name: formId
        in: path
        required: true
        schema:
          type: string
        description: The public identifier of the form
      - name: submissionId
        in: path
        required: true
        schema:
          type: string
        description: The identifier of the submission
      - name: includeEditLink
        in: query
        schema:
          type: boolean
        description: Pass true to include a link to edit the submission as 'editLink'
      responses:
        '200':
          description: Single submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleSubmissionResponse'
    delete:
      summary: Delete submission by ID
      description: Deletes a submission by its ID
      operationId: deleteSubmissionById
      parameters:
      - name: formId
        in: path
        required: true
        schema:
          type: string
        description: The public identifier of the form
      - name: submissionId
        in: path
        required: true
        schema:
          type: string
        description: The identifier of the submission
      responses:
        '200':
          description: Submission deleted successfully
  /webhook/create:
    post:
      summary: Create a webhook
      description: Creates a webhook for a given form
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWebhookResponse'
  /webhook/delete:
    post:
      summary: Remove a webhook
      description: Removes a webhook
      operationId: removeWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveWebhookRequest'
      responses:
        '200':
          description: Webhook removed successfully
          content:
            application/json:
              schema:
                type: object
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        Enter your [Fillout API key](https://build.fillout.com/home/settings/developer). Format: Bearer <api_key>
  schemas:
    FormSummary:
      type: object
      properties:
        name:
          type: string
          description: The name of the form
        formId:
          type: string
          description: The public identifier of the form
      required:
      - name
      - formId
    FormMetadata:
      type: object
      properties:
        id:
          type: string
          description: The public identifier of the form
        name:
          type: string
          description: The name of the form
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
          description: List of questions in the form
        calculations:
          type: array
          items:
            $ref: '#/components/schemas/Calculation'
          description: List of calculations in the form
        urlParameters:
          type: array
          items:
            $ref: '#/components/schemas/UrlParameter'
          description: List of URL parameters
        scheduling:
          type: array
          items:
            $ref: '#/components/schemas/SchedulingField'
          description: List of scheduling fields (if using Fillout Scheduling)
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentField'
          description: List of payment fields (if using Fillout Payments)
        quiz:
          $ref: '#/components/schemas/QuizConfig'
          description: Quiz configuration (only defined if quiz mode is enabled)
      required:
      - id
      - name
      - questions
    Question:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the question
        name:
          type: string
          description: The question text
        type:
          type: string
          enum:
          - Address
          - AudioRecording
          - Calcom
          - Calendly
          - Captcha
          - Checkbox
          - Checkboxes
          - ColorPicker
          - CurrencyInput
          - DatePicker
          - DateRange
          - DateTimePicker
          - Dropdown
          - EmailInput
          - FileUpload
          - ImagePicker
          - LocationCoordinates
          - LongAnswer
          - Matrix
          - MultiSelect
          - MultipleChoice
          - NumberInput
          - OpinionScale
          - Password
          - Payment
          - PhoneNumber
          - Ranking
          - RecordPicker
          - ShortAnswer
          - Signature
          - Slider
          - StarRating
          - Subform
          - SubmissionPicker
          - Switch
          - Table
          - TimePicker
          - URLInput
          description: The type of the question
      required:
      - id
      - name
      - type
    Calculation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the calculation
        name:
          type: string
          description: The name of the calculation
        type:
          type: string
          enum:
          - number
          - text
          - duration
          description: The type of the calculation
      required:
      - id
      - name
      - type
    UrlParameter:
      type: object
      properties:
        id:
          type: string
          description: Identifier for the URL parameter
        name:
          type: string
          description: Name of the URL parameter
      required:
      - id
      - name
    SchedulingField:
      type: object
      properties:
        id:
          type: string
          description: Identifier for the scheduling field
        name:
          type: string
          description: Name of the scheduling field
      required:
      - id
      - name
    PaymentField:
      type: object
      properties:
        id:
          type: string
          description: Identifier for the payment field
        name:
          type: string
          description: Name of the payment field
      required:
      - id
      - name
    QuizConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether quiz mode is enabled
      required:
      - enabled
    SubmissionsResponse:
      type: object
      properties:
        responses:
          type: array
          items:
            $ref: '#/components/schemas/Submission'
          description: List of submissions
        totalResponses:
          type: integer
          description: Total number of submissions matching given parameters
        pageCount:
          type: integer
          description: Total number of pages of submissions based on provided limit
      required:
      - responses
      - totalResponses
      - pageCount
    Submission:
      type: object
      properties:
        submissionId:
          type: string
          description: Unique identifier for the submission
        submissionTime:
          type: string
          format: date-time
          description: When the submission was made
        lastUpdatedAt:
          type: string
          format: date-time
          description: When the submission was last updated
        questions:
          type: array
          items:
            $ref: '#/components/schemas/QuestionResponse'
          description: List of question responses
        calculations:
          type: array
          items:
            $ref: '#/components/schemas/CalculationResponse'
          description: List of calculation responses
        urlParameters:
          type: array
          items:
            $ref: '#/components/schemas/UrlParameterResponse'
          description: List of URL parameter values
        scheduling:
          type: array
          items:
            $ref: '#/components/schemas/SchedulingResponse'
          description: List of scheduling responses (if using Fillout Scheduling)
        payments:
          type: array
          items:
            $ref: '#/components/schemas/PaymentResponse'
          description: List of payment responses (if using Fillout Payments)
        quiz:
          $ref: '#/components/schemas/QuizResponse'
          description: Quiz results (if form is configured as quiz)
        login:
          $ref: '#/components/schemas/LoginResponse'
          description: Login information (if using login page)
      required:
      - submissionId
      - submissionTime
      - questions
    QuestionResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the question
        name:
          type: string
          description: The question text
        type:
          type: string
          description: The type of the question
        value:
          description: The response value
      required:
      - id
      - name
      - type
      - value
    CalculationResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the calculation
        name:
          type: string
          description: Name of the calculation
        type:
          type: string
          enum:
          - number
          - text
          - duration
          description: Type of the calculation
        value:
          type: string
          description: The calculated value
      required:
      - id
      - name
      - type
      - value
    UrlParameterResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the URL parameter
        name:
          type: string
          description: Name of the URL parameter
        value:
          type: string
          description: Value of the URL parameter
      required:
      - id
      - name
      - value
    SchedulingResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the scheduling field
        name:
          type: string
          description: Name of the scheduling field
        value:
          $ref: '#/components/schemas/SchedulingValue'
          description: Scheduling details
      required:
      - id
      - name
      - value
    SchedulingValue:
      type: object
      properties:
        fullName:
          type: string
          description: Full name of the person booking
        email:
          type: string
          format: email
          description: Email of the person booking
        timezone:
          type: string
          description: Timezone for the meeting
        eventStartTime:
          type: string
          format: date-time
          description: Start time of the event
        eventEndTime:
          type: string
          format: date-time
          description: End time of the event
        eventId:
          type: string
          description: Calendar event ID
        eventUrl:
          type: string
          format: uri
          description: URL to the calendar event
        rescheduleOrCancelUrl:
          type: string
          format: uri
          description: URL to reschedule or cancel the event
        userId:
          type: integer
          description: User ID (optional)
        scheduledUserEmail:
          type: string
          format: email
          description: Email of the scheduled user (optional)
        meetingNotes:
          type: string
          description: Meeting notes (optional)
      required:
      - fullName
      - email
      - timezone
      - eventStartTime
      - eventEndTime
    PaymentResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the payment field
        name:
          type: string
          description: Name of the payment field
        value:
          $ref: '#/components/schemas/PaymentValue'
          description: Payment details
      required:
      - id
      - name
      - value
    PaymentValue:
      type: object
      properties:
        paymentId:
          type: string
          description: Stripe payment ID
        stripeCustomerId:
          type: string
          description: Stripe customer ID (optional)
        stripeCustomerUrl:
          type: string
          format: uri
          description: URL to Stripe customer dashboard (optional)
        stripePaymentUrl:
          type: string
          format: uri
          description: URL to Stripe payment dashboard (optional)
        totalAmount:
          type: integer
          description: Total amount in cents (optional)
        currency:
          type: string
          description: Currency code (optional)
        email:
          type: string
          format: email
          description: Customer email (optional)
        discountCode:
          type: string
          description: Discount code used (optional)
        status:
          type: string
          description: Payment status (optional)
        stripeSubscriptionId:
          type: string
          description: Stripe subscription ID (optional)
      required:
      - paymentId
    QuizResponse:
      type: object
      properties:
        score:
          type: integer
          description: Quiz score
        maxScore:
          type: integer
          description: Maximum possible score
      required:
      - score
      - maxScore
    LoginResponse:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Verified email address
      required:
      - email
    SingleSubmissionResponse:
      type: object
      properties:
        submission:
          $ref: '#/components/schemas/Submission'
          description: The submission data
      required:
      - submission
    CreateSubmissionsRequest:
      type: object
      properties:
        submissions:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/CreateSubmissionData'
          description: List of submissions to create (maximum 10)
      required:
      - submissions
    CreateSubmissionData:
      type: object
      properties:
        questions:
          type: array
          items:
            $ref: '#/components/schemas/CreateQuestionResponse'
          description: List of question responses (required)
        urlParameters:
          type: array
          items:
            $ref: '#/components/schemas/UrlParameterResponse'
          description: List of URL parameter values (optional)
        submissionTime:
          type: string
          format: date-time
          description: When the submission was made (optional)
        lastUpdatedAt:
          type: string
          format: date-time
          description: When the submission was last updated (optional)
        scheduling:
          type: array
          items:
            $ref: '#/components/schemas/CreateSchedulingResponse'
          description: List of scheduling responses (optional)
        payments:
          type: array
          items:
            $ref: '#/components/schemas/CreatePaymentResponse'
          description: List of payment responses (optional)
        login:
          $ref: '#/components/schemas/LoginResponse'
          description: Login information (optional)
      required:
      - questions
    CreateQuestionResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the question
        value:
          description: The response value
      required:
      - id
      - value
    CreateSchedulingResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the scheduling field
        value:
          $ref: '#/components/schemas/CreateSchedulingValue'
          description: Scheduling details
      required:
      - id
      - value
    CreateSchedulingValue:
      type: object
      properties:
        fullName:
          type: string
          description: Full name of the person booking
        email:
          type: string
          format: email
          description: Email of the person booking
        eventStartTime:
          type: string
          format: date-time
          description: Start time of the event
        eventEndTime:
          type: string
          format: date-time
          description: End time of the event
        timezone:
          type: string
          description: Timezone for the meeting
        userId:
          type: integer
          description: User ID (optional)
        scheduledUserEmail:
          type: string
          format: email
          description: Email of the scheduled user (optional)
        eventId:
          type: string
          description: Calendar event ID (optional)
        eventUrl:
          type: string
          format: uri
          description: URL to the calendar event (optional)
        rescheduleOrCancelUrl:
          type: string
          format: uri
          description: URL to reschedule or cancel the event (optional)
        meetingNotes:
          type: string
          description: Meeting notes (optional)
      required:
      - fullName
      - email
      - eventStartTime
      - eventEndTime
      - timezone
    CreatePaymentResponse:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the payment field
        value:
          $ref: '#/components/schemas/CreatePaymentValue'
          description: Payment details
      required:
      - id
      - value
    CreatePaymentValue:
      type: object
      properties:
        paymentId:
          type: string
          description: Stripe payment ID
        stripeCustomerId:
          type: string
          description: Stripe customer ID (optional)
        stripeCustomerUrl:
          type: string
          format: uri
          description: URL to Stripe customer dashboard (optional)
        stripePaymentUrl:
          type: string
          format: uri
          description: URL to Stripe payment dashboard (optional)
        totalAmount:
          type: integer
          description: Total amount in cents (optional)
        currency:
          type: string
          description: Currency code (optional)
        email:
          type: string
          format: email
          description: Customer email (optional)
        status:
          type: string
          description: Payment status (optional)
        stripeSubscriptionId:
          type: string
          description: Stripe subscription ID (optional)
      required:
      - paymentId
    CreateSubmissionsResponse:
      type: object
      properties:
        submissions:
          type: array
          items:
            $ref: '#/components/schemas/Submission'
          description: List of created submissions
      required:
      - submissions
    CreateWebhookRequest:
      type: object
      properties:
        formId:
          type: string
          description: The public identifier of the form for which you want to create a webhook
        url:
          type: string
          format: uri
          description: The endpoint where you'd like to listen for submissions
      required:
      - formId
      - url
    CreateWebhookResponse:
      type: object
      properties:
        id:
          type: integer
          description: The webhook ID
      required:
      - id
    RemoveWebhookRequest:
      type: object
      properties:
        webhookId:
          type: string
          description: The ID of the webhook you received when you created it
      required:
      - webhookId