logo

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.
Image without caption
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:
  1. date: Filter submissions by the number of days ago. For example, date:7 filters submissions created within the last 7 days.
  1. attachments: Filter submissions based on whether they have attachments or not. Use true for submissions with attachments and false for submissions without attachments.
  1. spam: Filter submissions based on whether they are marked as spam or not. Use true for spam submissions and false for non-spam submissions.
  1. 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
    • Image without caption

Powered by Notaku