Forminit JS SDK Reference

The official JavaScript/TypeScript SDK for Forminit form backend service.

---

# npm
npm install forminit

# yarn
yarn add forminit

# pnpm
pnpm add forminit

<script src="https://forminit.com/sdk/v1/forminit.js"></script>

---

const forminit = new Forminit({ proxyUrl: '/api/forminit' });

const form = document.getElementById('contact-form');
form.addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const formData = new FormData(form);
  const { data, error } = await forminit.submit('YOUR_FORM_ID', formData);
  
  if (error) {
    console.error(error.message);
    return;
  }
  
  console.log('Submission ID:', data.hashId);
});

import { Forminit } from 'forminit';

const forminit = new Forminit({
  apiKey: process.env.FORMINIT_API_KEY,
});

const { data, error } = await forminit.submit('YOUR_FORM_ID', {
  blocks: [
    {
      type: 'sender',
      properties: {
        email: '[email protected]',
        firstName: 'John',
        lastName: 'Doe',
      },
    },
    {
      type: 'text',
      name: 'message',
      value: 'Hello world',
    },
  ],
});

---

Option	Type	Description
proxyUrl	string	Client-side proxy URL to protect API key
apiKey	string	Server-side API key for authentication

Client-side:

const forminit = new Forminit({ proxyUrl: '/api/forminit' });

Server-side:

const forminit = new Forminit({ apiKey: process.env.FORMINIT_API_KEY });

---

new Forminit(config?)

Options:

Option	Type	Description
proxyUrl	string	Client-side proxy URL to protect API key
apiKey	string	Server-side API key for authentication

forminit.submit(formId, data)

Submits form data to Forminit.

Parameters:

Parameter	Type	Description
formId	string	Your Forminit form ID
data	FormData or object	Form data to submit

Returns: Promise with { data, redirectUrl, error }

forminit.setUserInfo({ ip, userAgent, referer })

Sets user information for server-side submissions. Used when submitting on behalf of a user.

Parameters:

Parameter	Type	Description
ip	string	User’s IP address
userAgent	string	User’s browser user agent
referer	string	Referring page URL

---

Use standard HTML form field naming with the fi- prefix:

<form id="contact-form">
  <input type="email" name="fi-sender-email" required />
  <input type="text" name="fi-sender-firstName" required />
  <input type="text" name="fi-sender-lastName" required />
  <textarea name="fi-text-message" required></textarea>
  <button type="submit">Send</button>
</form>

Field Naming Patterns:

Block Type	Pattern	Example
Sender properties	fi-sender-{property}	fi-sender-email
Text	fi-text-{name}	fi-text-message
Number	fi-number-{name}	fi-number-quantity