# 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
andgetform_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.