Getting started overview

This guide provides a structured approach to initiating development with Formstack, focusing on the essential steps required to make an authenticated API call. Formstack facilitates data collection, workflow automation, and digital document generation through its suite of products, including Formstack Forms, Documents, and Sign. To begin, users typically create a paid account, generate API credentials, and then utilize these credentials to interact with the Formstack API.

The Formstack API allows for programmatic interaction with forms, submissions, and other platform features, enabling integration into existing applications or custom development. Understanding the authentication mechanism and endpoint structure is foundational for successful integration.

The process outlined here covers account creation, credential generation, and a practical example of making a successful API request. For comprehensive details on specific endpoints and advanced features, refer to the Formstack support documentation.

Create an account and get keys

Access to Formstack's developer features, including its API, requires an active Formstack account. As a free tier is not available, a paid subscription is necessary. Formstack offers several pricing tiers, starting with a Starter plan for individual or small team use, scaling up to Enterprise solutions for larger organizations. Details on the subscription plans and their features, such as number of forms and submissions, are available on the Formstack pricing page.

Follow these steps to set up your account and retrieve your API credentials:

  1. Sign Up for a Formstack Account: Navigate to the Formstack website and select a suitable plan. Complete the registration process by providing the required information and payment details.
  2. Log In to Your Account: Once your account is active, log in to the Formstack dashboard using your newly created credentials.
  3. Access API Settings: In the dashboard, locate and click on your profile icon or name, typically in the top right corner. From the dropdown menu, select API or API Settings. This section is where API keys are managed.
  4. Generate API Key and Secret: Within the API settings, you will find options to generate new API credentials. Formstack typically uses an API Key and an API Secret for authentication. Click on the button to generate a new key pair.
  5. Record Your Credentials: The API Key and Secret will be displayed. It is critical to copy and securely store both values immediately, as the API Secret is often displayed only once upon generation for security reasons. If lost, you may need to regenerate a new secret, invalidating the previous one.

These credentials will be used for authenticating your API requests. Formstack generally employs Basic Authentication for its API, where the API Key serves as the username and the API Secret serves as the password in the HTTP Authorization header. For more information on securing API keys, consult general best practices for API key security.

Your first request

After acquiring your API Key and Secret, you can proceed with making your first authenticated request to the Formstack API. This example demonstrates fetching a list of your forms using a simple HTTP GET request. We will use curl for this example, which is a common command-line tool for making HTTP requests.

API Endpoint Structure

The base URL for the Formstack API is https://www.formstack.com/api/v2/. All subsequent endpoint paths are appended to this base URL.

Authentication

Formstack's API typically uses Basic Authentication. This means you will encode your API Key and Secret into a base64 string and include it in the Authorization header of your HTTP request. The format is Basic <base64_encoded_credentials>, where base64_encoded_credentials is API_KEY:API_SECRET base64-encoded.

# Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials
API_KEY="YOUR_API_KEY"
API_SECRET="YOUR_API_SECRET"

# Combine and base64 encode for Basic Auth
AUTH_STRING=$(echo -n "${API_KEY}:${API_SECRET}" | base64)

# Make the API request to list forms
curl -X GET \
  "https://www.formstack.com/api/v2/form.json" \
  -H "Accept: application/json" \
  -H "Authorization: Basic ${AUTH_STRING}"

This curl command performs the following actions:

  • -X GET: Specifies that this is an HTTP GET request.
  • "https://www.formstack.com/api/v2/form.json": The API endpoint to retrieve a list of forms.
  • -H "Accept: application/json": Requests the response in JSON format.
  • -H "Authorization: Basic ${AUTH_STRING}": Provides the Basic Authentication header using your base64-encoded API Key and Secret.

Expected Response

A successful response (HTTP status code 200 OK) will return a JSON array containing details of your forms. If you have no forms created, the array might be empty or contain minimal information. An example of a successful response might look like this:

[
  {
    "id": "1234567",
    "name": "Contact Us Form",
    "url": "https://www.formstack.com/forms/1234567",
    "status": "active",
    "submissions": "150"
  },
  {
    "id": "8901234",
    "name": "Event Registration",
    "url": "https://www.formstack.com/forms/8901234",
    "status": "active",
    "submissions": "75"
  }
]

This response confirms that your API credentials are valid and that you can successfully communicate with the Formstack API.

Common next steps

Once you have successfully made your first API call, you can explore more advanced functionalities provided by the Formstack API. Common next steps often involve specific use cases related to data collection, integration, or automation.

Formstack API Common Next Steps
Step What to Do Where to Find Info
Create and Manage Forms Programmatically create new forms, update existing form structures, or delete forms. Formstack API Documentation on Forms
Retrieve and Submit Data Fetch form submissions (entries) or submit data to a form via the API. This is crucial for integrating Formstack with other systems. Submitting Forms with the API
Webhooks for Real-time Data Set up webhooks to receive real-time notifications when a form is submitted. This enables event-driven integrations. Formstack Webhooks Guide
Integrate with Formstack Documents Use the Formstack Documents API to generate documents (e.g., PDFs, Word docs) from form submissions or other data. Formstack Documents API Reference
Formstack Sign Integration Integrate with Formstack Sign for e-signature workflows, automating signature requests and document routing. Formstack Sign API Documentation
Error Handling and Monitoring Implement robust error handling in your applications and set up monitoring for API calls to ensure reliability. General API development best practices (e.g., Google Developers API Error Handling)

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems along with their solutions:

  • 401 Unauthorized Error:

    • Issue: This indicates that your authentication credentials are incorrect or missing.
    • Solution: Double-check your API Key and API Secret for typos. Ensure they are correctly base64 encoded and placed in the Authorization: Basic header. Remember that secrets are case-sensitive. If you regenerated your secret, ensure you are using the latest one.

  • 403 Forbidden Error:

    • Issue: Your credentials are valid, but the user associated with the API key does not have the necessary permissions to access the requested resource.
    • Solution: Verify that the Formstack account associated with your API key has the correct permissions for the action you're trying to perform (e.g., accessing forms, submissions). Check your account's user roles and permissions within the Formstack dashboard.

  • 404 Not Found Error:

    • Issue: The API endpoint you are trying to reach does not exist or the resource (e.g., a specific form ID) cannot be found.
    • Solution: Review the API endpoint URL for typos. Consult the Formstack API documentation to confirm the correct endpoint paths. If you are requesting a specific form, ensure the form ID is correct and the form exists.

  • Network Connectivity Issues:

    • Issue: Your request is not reaching the Formstack servers due to network problems.
    • Solution: Check your internet connection. Try reaching https://www.formstack.com in a web browser. Ensure no firewalls or proxy settings are blocking outgoing requests from your development environment.

  • Incorrect JSON Format in Request Body (for POST/PUT requests):

    • Issue: If you are making a POST or PUT request, the JSON payload in your request body might be malformed.
    • Solution: Validate your JSON payload using an online JSON validator. Ensure all required fields are present and correctly formatted according to the Formstack API documentation for the specific endpoint.

  • Rate Limiting:

    • Issue: Your application is sending too many requests in a short period, leading to a 429 Too Many Requests error.
    • Solution: Implement exponential backoff or other rate-limiting strategies in your application. Consult Formstack's documentation for specific rate limit thresholds, if available.

For persistent issues, reviewing the Formstack API documentation and support resources is recommended. Many common issues have dedicated troubleshooting guides within their Help Center.