Responses REST API

The Responses API lets you retrieve form responses submitted by users for a specific Fillout form. This help article explains the parameters, request format, and response structure for the API.

The Fillout API is currently only available on the Enterprise plan. Note that webhooks are available on all plans.

Authentication Example Request with Authentication API Parameters Response Structure

For a list of other REST API endpoints, see this article.

Authentication

The Fillout Responses API uses Bearer Authentication. 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.

To get your API key:

Go to https://build.fillout.com/home/enterprise (enterprise plan only).

Navigate to the REST API tab.

Enable the REST API for your account and copy the key.

Example Request with Authentication

Here is an example request that includes the Authorization header with a Bearer token:


GET https://api.fillout.com/v1/forms/<your-form-id>/responses?limit=50&after_date=2023-05-01T00:00:00.000Z&offset=0

Authorization: Bearer <your-api-key>

Replace <your-api-key> with your actual API key and <your-form-id> with the form ID of the form you want to get responses for. Make sure to include the Authorization header in all your API requests.

API Parameters

Below are the parameters you can provide when making a request to the API:

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

limit: (optional) The maximum number of responses to retrieve per request. Must be a number between 1 and 150. Default is 150.

after_date: (optional) A date string to filter responses submitted after this date.

before_date: (optional) A date string to filter responses submitted before this date.

offset: (optional) The starting position from which to fetch the responses. Default is 0.

Date format

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

Response Structure

The API will return a JSON object containing the following keys:

responses: An array of form response objects that match the given parameters.

total_responses: The total number of responses that match the given parameters.

page_count: The total number of pages of responses based on the provided limit.

Example response:


{
  "responses": [
    {
      "answers": [
        {
          "value": "+99832123123123",
          "field": {
            "id": "7DYPJHVdsCrdN2BNV9dtDN",
            "label": "Phone number",
            "type": "PhoneNumber"
          }
        },
        {
          "value": "email@gmail.com",
          "field": {
            "id": "pztmsPxQjzXYugNyMz8jUE",
            "label": "Email",
            "type": "EmailInput"
          }
        }
      ],
      "submitted_at": "2022-07-19T15:54:08.323Z",
      "metadata": {
                "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/111.0.0.0 Safari/533.36"
            }
    },
    // ... More response objects
  ],
  "total_responses": 13,
  "page_count": 1
}