Submissions API

In this section, we will discuss the Form Submissions API, which allows you to retrieve a list of submissions for a specific form. This API supports pagination, filtering, and sorting options to help you fetch the data you need.

Base URL

The base URL for the Form Submissions API is https://formcarry.com/api/form

Authorization

Internal API works pretty easy to begin with, every team has an API key that can be found under Integrations.

Copy this key first, you are going to use it for authorization along the way.

Example Authorization:

💡

Please pass your api_key in request header at every request you made to the API

With curl:

shell
curl -H "api_key: YOUR_API_KEY" https://formcarry.com/api/auth

With Javascript:

javascript
// Create an object to store the request headers
var headers = {
    "api_key": "Change With Your API Key"
};

// Use the fetch API to send a request with the specified headers
fetch("https://formcarry.com/api/auth", {
    headers: headers
})
.then(function (response) {
    // Print the response to the console
    console.log(response);
})
.catch(function (error) {
    // Print any error that occurred
    console.error(error);
});

Example Response:

json
{
	"status":"success",
	"message":"You are successfully authenticated, please pass your api_key in every requests header."
}

Retrieve Form Submissions

Use the following endpoint to retrieve form submissions:

json
GET https://formcarry.com/api/form/:formid/submissions

Path Parameters

formid: Required. The unique identifier for the form whose submissions you want to retrieve.

Query Parameters

limit: Optional. The number of submissions to return per page. Default is 25, and the maximum value is 50.

page: Optional. The page number to return. Default is 1.

sort: Optional. The sorting criteria for the submissions. Use the format field:order, where field is the field to sort by and order is either 1 (ascending) or -1 (descending). By default, submissions are sorted by createdAt in descending order.

filter: Optional. Apply filters to the submissions using the filter query parameter. Filters should be in the format key:value, and multiple filters can be separated by commas.

Available filters:

date: Filter submissions by the number of days ago. For example, date:7 filters submissions created within the last 7 days.

attachments: Filter submissions based on whether they have attachments or not. Use true for submissions with attachments and false for submissions without attachments.

spam: Filter submissions based on whether they are marked as spam or not. Use true for spam submissions and false for non-spam submissions.

Custom filters for dynamic fields: Filter submissions based on specific field values. Use the format fieldname_contains:value to include submissions containing the value, and fieldname_notcontains:value to exclude submissions containing the value.

Note: Filtering by dynamic fields can be vulnerable to user input, so it's important to properly sanitize and validate the input to prevent potential security issues.

Response

The response is a JSON object containing the following properties:

form: The unique identifier of the form whose submissions were requested.

results: The number of submissions returned in the current response.

pagination: An object containing pagination details.

current_page: The current page number.
previous_page: The previous page number, or null if there is no previous page.
next_page: The next page number, or null if there is no next page.
total_page: The total number of pages.
total_submissions: The total number of submissions for the form.

submissions: An array of submission objects. Each object contains the following properties:

_id: The unique identifier of the submission.
form: The unique identifier of the form the submission is associated with.
createdAt: The timestamp when the submission was created.
updatedAt: The timestamp when the submission was last updated.
fields: An array of objects containing the field values for the submission. Each object includes