Fillout REST API

Interact with Fillout via a REST API. Access your forms and form submissions from outside the Fillout site.

What is REST API Introduction Authentication API Endpoints Get forms Response Get form metadata Request parameters:Response:Get all submissions Request Response Get submission by id Request Response Create a webhook Request Response Remove a webhook Request Response:Rate limits Related articles

What is REST API

A REST API simplifies interaction with your form data, allowing for automation and integration. Following RESTful principles, it seamlessly connects to retrieve, create, and modify form data.

Introduction

The Fillout API lets you access information about your Fillout account programmatically, without using the Fillout site. The Fillout API is primarily for Fillout users and for 3rd party developers that want to build services on top of Fillout.

You can access a list of all your forms and the submissions for each form via the API. You can also create new forms and activate, deactivate and publish existing forms.

Authentication

Generate and view your API key in the Developer settings tab of your account. You can revoke or regenerate your API key at any time via the dashboard.

To authenticate your requests, you need to provide your API key in the Authorization header in the following format:


Authorization: Bearer <your-api-key>

Replace <your-api-key> with the API key obtained from your Fillout account.

You can obtain your API base URL in the API dashboard. Typically, it will be https://api.fillout.com.

☑️

Important: If you’re self-hosting Fillout or using the EU agent, a different URL will appear in the dashboard.

ℹ️

Note: you can also use access tokens granted via a Fillout 3rd party integration. If you’re looking to build an integration, see this article.

API Endpoints

Get forms

GET /v1/api/forms

Response

Returns a list of all your forms.


[
    {
        "name": "My example form",
        "formId": "vso9PzRfHQus",
    },
    ...
]

Get form metadata

GET /v1/api/forms/{formId}

Request parameters:

URL parameters:

formId (the public ID of your form, you can find from /v1/api/forms)

Response:

Given the formId, returns all the questions in that form and other metadata.


{
	"id": "vso9PzRfHQus",
	"name": "My example form",
  "questions": [        
      {
          "id": "5AtgG35AAZVcrSVfRubvp1",
          "name": "What's your email?",
          "type": "Email"
      },
      {
          "id": "gRBWVbE2fut2oiAMprdZpY",
          "name": "What is your name?",
          "type": "ShortAnswer"
      },
      {
          "id": "hP4bHA1CgvyD2LKhBnnGHy",
          "name": "Pick your favorite color",
          "type": "MultipleChoice"
      }
  ],
	"calculations": [
		{
			"id": "abcdef",
			"name": "Price",
			"type": "number"
		}
	],
	"urlParameters": [
		{
			"id": "email",
			"name": "email"
		}
	],
}

The full list of possible question types:

'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', 'Switch', 'TimePicker', 'URLInput'

The full list of possible calculations: 'number', 'text'

⚠️

New field types are added regularly. Your application should discard fields with unknown types.

Get all submissions

GET /v1/api/forms/{formId}/submissions

Request

URL parameters:

formId (required) - the public identifier of the form for which you want to retrieve submissions. This should be a string. If your form’s URL is https://form.fillout.com/t/gHretr3UKYus, the form ID is gHretr3UKYus

Query parameters:

limit(optional) - the maximum number of submissions to retrieve per request. Must be a number between 1 and 150. Default is 150.

afterDate (optional) - a date string to filter submissions submitted after this date

beforeDate (optional) - a date string to filter submissions submitted before this date

offset(optional) - the starting position from which to fetch the submissions. Default is 0.

status(optional) - pass in_progress to get a list of in-progress (unfinished) submissions. By default, only finished submissions are returned. Note that fetching in progress submissions is available starting on the business plan.

includeEditLink (optional) - pass true to include a link to edit the submission as editLink

sort (optional) - can be asc or desc, defaults to asc

Date format

Both afterDate and beforeDate parameters should be provided in the following format: YYYY-MM-DDTHH:mm:ss.sssZ. For example: 2024-05-16T23:20:05.324Z.

Response


{
	"responses": [
		{
			"questions": [
				{
					"id": "abcdef",
					"name": "What's your name?",
					"type": "ShortAnswer",
					"value": "Timmy"
				},
			],
			"calculations": [
				{
					"id": "calculation1",
					"name": "price",
					"type": "number",
					"value": "12.50"
				}
			],
			"urlParameters": [
				{
					"id": "email",
					"name": "email",
					"value": "example@example.com",
				}
			],
			// optional depending on if form is configured to be a quiz
			"quiz": {
				"score": 5,
				"maxScore": 10
			},
			"submissionId": "abc",
			"submissionTime": "2024-05-16T23:20:05.324Z"
		},
	],
	"totalResponses": 300, // total number of submissions matching given parameters
	"pageCount": 2 // total number of pages of submissions based on provided limit
}

The question’s type will be a question type listed in the previous section (such as EmailInput), while the type for a calculation is either number or text

⚠️

New field types are added regularly. Your application should discard fields with unknown types.

Get submission by id

GET /v1/api/forms/{formId}/submissions/{submissionId}

Request

URL parameters:

formId (required) - the public identifier of the form for which you want to retrieve submissions. This should be a string. If your form’s URL is https://form.fillout.com/t/gHretr3UKYus, the form ID is gHretr3UKYus

submissionId (required) - the identifier of the submission

Query parameters:

includeEditLink (optional) - pass true to include a link to edit the submission as editLink

Response

Same as the “Get all submissions” endpoint but only returns a single item


{
	"submission": {
		"questions": [
			{
				"id": "abcdef",
				"name": "What's your name?",
				"type": "ShortAnswer",
				"value": "Timmy"
			},
		],
		"calculations": [
			{
				"id": "calculation1",
				"name": "price",
				"type": "number",
				"value": "12.50"
			}
		],
		"urlParameters": [
			{
				"id": "email",
				"name": "email",
				"value": "example@example.com",
			}
		],
		// optional depending on if form is configured to be a quiz
		"quiz": {
			"score": 5,
			"maxScore": 10
		},
		"submissionId": "abc",
		"submissionTime": "2024-05-16T23:20:05.324Z"
	}
}

Create a webhook

POST /v1/api/webhook/create

Request

Body parameters:

formId (required) - the public identifier of the form for which you want to retrieve submissions. This should be a string.

url (required) - the endpoint where you’d like to listen for submissions

Response


{
	"id": 12345
}

Once subscribed, your webhook will receive submissions in the same format as the entries in the responses list from the /submissions endpoint above.

Remove a webhook

POST /v1/api/webhook/delete

Request

Body parameters:

webhookId (required) - the ID of the webhook you received when you created it.

Response:

N/A

Rate limits

All endpoints above are limited to being called no more than 5 times per second, per Account/API key.

📱

Create Fillout 3rd Party Apps

⚡

Send form submissions to a webhook