{
  "openapi": "3.0.1",
  "info": {
    "title": "Fillout REST API",
    "description": "A REST API for managing forms, submissions, and webhooks in Fillout",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.fillout.com/v1/api",
      "description": "US server"
    },
    {
      "url": "https://eu-api.fillout.com/v1/api",
      "description": "EU server"
    }
  ],
  "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"]
      }
    }
  }
}