Skip to main content

How to Use the FormMaker API

This guide provides detailed instructions on how to use the FormMaker API to submit form data programmatically to your FormMaker forms.

Authorization​

To interact with the API, you'll need to generate an API key from your FormMaker dashboard.

Generating an API Key​

  1. Sign in to Your FormMaker Account

    • Go to FormMaker and log in with your credentials.

  2. Generate API Key

    • Navigate to your dashboard or profile settings
    • Look for the "Generate API Key" option
    • Click on Generate New Key
    • Important: Copy the API key and store it securely. This key is unique and cannot be recovered if lost.

Using the API Key​

Include your API key in the Authorization header of your HTTP requests using Bearer authentication.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Example in JavaScript:

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${yourApiKey}`,
};

Making a Request​

To submit data to one of your forms via the API, send a POST request to:

https://formmaker.co.in/api/app

Request Headers​

Include the following headers in your request:

  • Content-Type: application/json
  • Authorization: Bearer YOUR_API_KEY

Request Body​

The request body should be a JSON object containing:

  • id: The unique identifier of your FormMaker form
  • properties: An object containing the form field data as key-value pairs
  • contact_id (optional): If updating an existing contact

Request Body Structure​

{
  "id": "your-form-id",
  "properties": {
    "email": "[email protected]",
    "firstname": "John",
    "lastname": "Doe",
    "company": "Example Corp"
  },
  "contact_id": "optional-existing-contact-id"
}

Obtaining Your Form ID​

  1. Access Your Forms

    • Go to your FormMaker dashboard
    • Navigate to your forms list

  2. Get Form ID

    • Select the form you want to use with the API
    • Copy the form's unique ID from the form settings or URL

Full Example Request​

Here's a complete example using JavaScript's fetch API:

const apiUrl = 'https://formmaker.co.in/api/app';
const apiKey = 'YOUR_API_KEY'; // Replace with your actual API key

const formData = {
  id: 'your-form-id', // Replace with your actual form ID
  properties: {
    email: '[email protected]',
    firstname: 'John',
    lastname: 'Doe',
    company: 'Example Company',
    phone: '+1234567890'
  }
};

fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`,
  },
  body: JSON.stringify(formData),
})
  .then((response) => response.json())
  .then((data) => {
    console.log('Success:', data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

Node.js Example with Axios​

const axios = require('axios');

const apiUrl = 'https://formmaker.co.in/api/app';
const apiKey = 'YOUR_API_KEY';

const formData = {
  id: 'your-form-id',
  properties: {
    email: '[email protected]',
    firstname: 'John',
    lastname: 'Doe'
  }
};

async function submitForm() {
  try {
    const response = await axios.post(apiUrl, formData, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`,
      },
    });
    console.log('Success:', response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

submitForm();

Handling the Response​

Upon a successful request, the API will return a response containing:

  • Status Code: 200 OK
  • Message: Confirmation message
  • Data: Response data from the form submission

Example Success Response:

{
  "message": "contact created",
  "data": {
    "inlineMessage": "Thank you for submitting the form.",
    "redirectUri": "",
    "errors": []
  }
}

Form Integration Features​

The FormMaker API supports various integration features:

HubSpot Integration​

  • Automatically creates or updates contacts in your connected HubSpot portal
  • Supports custom form submissions to specific HubSpot forms
  • Handles duplicate contact detection and updates

Credit System​

  • API usage is tracked against your account credits
  • Free plan users have limited submissions
  • Monthly/yearly subscribers get unlimited submissions

Email Notifications​

  • Automatic email notifications for form submissions
  • Customizable submission email addresses
  • Credit limit warnings and notifications

Error Handling​

Common errors you might encounter:

403 Forbidden - Invalid API Key​

{
  "message": "API key is missing"
}

or

{
  "message": "Invalid API key"
}

404 Not Found - Form Not Found​

When the form ID doesn't exist:

{
  "message": "Form not found"
}

500 Internal Server Error​

For server-side issues:

{
  "message": "Internal server error"
}

Best Practices for Error Handling​

  1. Always check HTTP status codes

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

  2. Validate your data before sending

    • Ensure required fields are present
    • Check data types and formats
    • Validate email formats if applicable

  3. Handle rate limits and credits

    • Monitor your account credit usage
    • Implement retry logic for temporary failures
    • Upgrade your plan if you exceed credit limits

  4. Secure your API key

    • Never expose API keys in client-side code
    • Store keys in environment variables
    • Rotate keys periodically for security

Rate Limits and Usage​

  • Free Plan: Limited number of submissions based on credits
  • Paid Plans: Unlimited API submissions
  • Rate Limiting: No explicit rate limits, but usage is tracked per account

Testing Your Integration​

Test with curl​

curl -X POST https://formmaker.co.in/api/app \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "id": "your-form-id",
    "properties": {
      "email": "[email protected]",
      "firstname": "Test",
      "lastname": "User"
    }
  }'

Validate Response​

Always validate the response to ensure successful submission:

fetch(apiUrl, requestOptions)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    if (data.message === 'contact created') {
      console.log('Form submitted successfully!');
    }
  })
  .catch(error => {
    console.error('Submission failed:', error);
  });

Additional Resources​