# Getform API

# API Authentication

The Getform API is organized around REST. Our API returns JSON-encoded responses, and uses standard HTTP response codes, authentication.

All Getform API endpoints accept authentication by passing your token as a GET parameter. You can find your form specific API token under your "Form Settings" page on your form dashboard.

# API Token Format

Here is the sample API token format of Getform API:

https://api.getform.io/v1/forms/{form_id}?token={getform_api_token}

TIPS

  • Each token you generate is form specific and you need to use a different token for each form.
  • Make sure to keep the API token secret. If you notice that it's been compromised, you can use "Refresh Token" button to regenerate it.
  • Make sure to change your form_id and getform_api_token in the call above with your unique form ID and API token, otherwise you won't get the correct response for your API call.

# Submission Endpoint

Using Getform API, you can programmatically query and filter your form submission data.

# Get Submissions

Using the submission API endpoint, you can return a list of submission data using various filtering options that are similar to the functionality available in your Getform submission dashboard.

# Sample Request

To fetch all your submission data, here is the example request:

curl -u https://api.getform.io/v1/forms/{form_id}?token={getform_api_token}

# Sample Response

This is a sample GET response.

{
   "success":true,
   "data":{
      "id":"3e7422dd-91b7-461b-a29f-7fef36fabe25",
      "submissions":[
         {
            "name": "John Doe",
            "email": "john@doe.com",
            "message": "Getform API is cool!",
            "id":14013383,
            "submissionDate":"03-02-2021 21:30",
         },
      ],
      "pagination":{
         "count":1,
         "currentPage":1,
         "total":1,
         "firstPage":1,
         "lastPage":1,
         "size":10
      }
   }
}

If you would like to get the uploaded files, you should add &files=true filtering option.

# Sample Request

curl -u https://api.getform.io/v1/forms/{form_id}?token={getform_api_token}&files=true

# Sample Response

{
   "success":true,
   "data":{
      "id":"3e7422dd-91b7-461b-a29f-7fef36fabe25",
      "submissions":[
         {
            "name": "John Doe",
            "email": "john@doe.com",
            "message": "Getform API is cool!",
            "id":14013383,
            "submissionDate":"03-02-2021 21:30",
             "files":[
               "https:\/\/files.getform.io\/3e7422dd-91b7-461b-a29f-7fef36fabe25\/JohnDoeResume.pdf"
            ]
         },
      ],
      "pagination":{
         "count":1,
         "currentPage":1,
         "total":1,
         "firstPage":1,
         "lastPage":1,
         "size":10
      }
   }
}

# Filtering Options

While you are requesting your form submission data, there are several filtering options you can use.

# Page Option

Use the page parameter option to gather the results from a specific page.

Example:

curl -u https://api.getform.io/v1/forms/form_id}?token={getform_api_token}&page=2

# Size Option

Use the size parameter option to limit the number of results. If you don't use this parameter the default size option will be applied as 10.

Example:

curl -u https://api.getform.io/v1/forms/form_id}?token={getform_api_token}&size=5

# Query Option

Use the query parameter option to search a specific term within your form submissions.

Example:

curl -u https://api.getform.io/v1/forms/form_id}?token={getform_api_token}&query=doe

# Timezone Option

Use the timezone parameter option to filter your submissions according to the timezone.

Example:

curl -u https://api.getform.io/v1/forms/form_id}?token={getform_api_token}&timezone=Europe/Istanbul

You can combine any request parameter with each other while making an API call.