JSONPost
Free HTML Form Generator
Beta
Sign InGet Started
Developer Documentation

JSONPost Integration Guide

Complete developer documentation for integrating JSONPost headless form backend into your frontend applications. Get started in minutes with our simple API.

Quick Start Get API Key

Table of Contents

Quick StartAuthenticationAPI ReferenceHTML FormsJavaScript/ReactFramework ExamplesFile UploadsWebhooksEmail NotificationsJSON ValidationSecurity

Quick Start

Get your form backend up and running in 3 simple steps.

1

Create Account & Project

Sign up for JSONPost and create your first project to get your unique endpoint URL.

2

Configure Endpoint

Set up your form endpoint with email notifications, webhooks, and custom settings.

3

Start Submitting

Point your forms to your JSONPost endpoint and start collecting submissions instantly.

Your First Form Submission

Here's how simple it is to submit data to JSONPost:

# Your JSONPost endpoint URL
https://jsonpost.com/api/submit/your-project-id/contact
# Submit with cURL
curl -X POST \
https://jsonpost.com/api/submit/your-project-id/contact \
-H "Content-Type: application/json" \
-d '{"name": "John Doe", "email": "john@example.com", "message": "Hello!"}'

Authentication

JSONPost provides flexible authentication options to match your security needs. Choose between public endpoints for simple forms or API key authentication for secure applications.

Flexible Authentication

JSONPost supports both public endpoints and secure API key authentication depending on your security requirements.

Public Endpoints

For simple contact forms and public submissions, no API key is required. Your project ID and endpoint path provide basic access control.

Secure Endpoints

Enable API key authentication for sensitive forms or when you need to restrict access to authorized applications only.

Security Note: You can configure each endpoint individually to require API key authentication through your dashboard.

Endpoint URL Structure

Every endpoint follows a consistent URL pattern for easy integration.

# URL Structure
https://jsonpost.com/api/submit/
[PROJECT_ID]
/
[ENDPOINT_PATH]
# Example
https://jsonpost.com/api/submit/
abc123-def456-ghi789
/
contact

API Reference

Complete reference for the JSONPost submission API.

Form Submission Endpoint

Submit form data to your JSONPost endpoint

Supported HTTP Methods

POST
PUT
PATCH
OPTIONS

Supported Content Types

  • application/json
  • application/x-www-form-urlencoded
  • multipart/form-data

Response Format

# Success Response (200)
{
"success": true,
"message": "Submission received successfully",
"submission_id": "uuid-here"
}
# Error Response (4xx/5xx)
{
"error": "Error message here"
}

CORS Support

JSONPost supports cross-origin requests from any domain

Full CORS Support: All JSONPost endpoints include proper CORS headers, allowing requests from any origin. Perfect for frontend applications, static sites, and SPAs.

HTML Forms

The simplest way to integrate JSONPost with traditional HTML forms.

Basic Contact Form

A simple contact form that submits directly to JSONPost

<form
action="https://jsonpost.com/api/submit/
your-project-id/contact"
method="POST">
<input
type="text"
name="name"
placeholder="Your Name"
required />
<input
type="email"
name="email"
placeholder="your@email.com"
required />
<textarea
name="message"
placeholder="Your message"
required></textarea>
<button type="submit">
Send Message
</button>
</form>

Advanced Form with Redirect

Form with hidden fields and custom redirect handling

<form
action="https://jsonpost.com/api/submit/
your-project-id/newsletter"
method="POST">
<!-- Visible fields -->
<input name="email" type="email" required />
<input name="name" type="text" />
<!-- Hidden metadata -->
<input type="hidden" name="source" value="homepage" />
<input type="hidden" name="campaign" value="summer2024" />
<button type="submit">Subscribe</button>
</form>

HTML Form Best Practices

✅ Do

  • • Use descriptive name attributes
  • • Include proper validation attributes
  • • Add hidden fields for tracking
  • • Use HTTPS for secure submissions
  • • Test form submissions thoroughly

❌ Don't

  • • Submit sensitive data without encryption
  • • Use generic field names like "field1"
  • • Forget to handle form submission errors
  • • Submit forms without user consent
  • • Ignore accessibility best practices

JavaScript & React Integration

Modern JavaScript and React examples for dynamic form handling.

Vanilla JavaScript with Fetch API

Handle form submissions with modern JavaScript

async function submitForm(formData) {
try {
const response = await fetch(
'https://jsonpost.com/api/submit/your-project-id/contact',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(formData)
}
);
const result = await response.json();
if (result.success) {
console.log('Form submitted successfully!');
// Handle success (show message, redirect, etc.)
} else {
console.error('Submission failed:', result.error);
}
} catch (error) {
console.error('Network error:', error);
}
}
// Usage
submitForm({
name: 'John Doe',
email: 'john@example.com',
message: 'Hello from JavaScript!'
});

React Hook for Form Handling

Custom React hook for JSONPost integration

import { useState } from 'react';
function useJSONPost(endpoint) {
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const [success, setSuccess] = useState(false);
const submit = async (data) => {
setLoading(true);
setError(null);
setSuccess(false);
try {
const response = await fetch(endpoint, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(data)
});
const result = await response.json();
if (result.success) {
setSuccess(true);
} else {
setError(result.error);
}
} catch (err) {
setError('Network error occurred');
} finally {
setLoading(false);
}
};
return { submit, loading, error, success };
}
// Usage in component
function ContactForm() {
const { submit, loading, error, success } = useJSONPost(
'https://jsonpost.com/api/submit/your-project-id/contact'
);
const handleSubmit = (e) => {
e.preventDefault();
const formData = new FormData(e.target);
submit(Object.fromEntries(formData));
};
return (
<form onSubmit={handleSubmit}>
{/* form fields */}
<button disabled={loading}>
{loading ? 'Sending...' : 'Send'}
</button>
</form>
);
}

Framework Examples

Integration examples for popular web frameworks and libraries.

Vue.js Integration

Using JSONPost with Vue.js and the Composition API

<template>
<form @submit.prevent="submitForm">
<input v-model="form.name" name="name" />
<input v-model="form.email" name="email" />
<button :disabled="loading">
{{ loading ? "Sending..." : "Send" }}
</button>
</form>
</template>
<script setup>
import { ref } from 'vue'
const form = ref({ name: "", email: "" })
const loading = ref(false)
const submitForm = async () => {
loading.value = true
const response = await fetch(
'https://jsonpost.com/api/submit/your-project-id/contact',
{ method: "POST", body: JSON.stringify(form.value) }
)
loading.value = false
}
</script>

Next.js Server Action

Using JSONPost with Next.js Server Actions

// app/actions.js
'use server'
export async function submitToJSONPost(formData) {
const data = {
name: formData.get('name'),
email: formData.get('email'),
message: formData.get('message')
}
try {
const response = await fetch(
'https://jsonpost.com/api/submit/your-project-id/contact',
{
method: 'POST',
headers: { "Content-Type": "application/json" },
body: JSON.stringify(data)
}
)
return await response.json()
} catch (error) {
return { error: "Failed to submit" }
}
}
// In your component
<form action={submitToJSONPost}>
/* form fields */
</form>

A
Astro Framework

Integrate JSONPost with Astro for both static sites and server-side rendering.

Static Form (Client-Side)

// src/components/ContactForm.astro
---
// Component script (runs at build time)
---
<form id="contact-form" class="space-y-4">
<div>
<label for="name">Name</label>
<input type="text" id="name" name="name" required />
</div>
<div>
<label for="email">Email</label>
<input type="email" id="email" name="email" required />
</div>
<div>
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
</div>
<button type="submit">Send Message</button>
</form>
<script>
document.getElementById('contact-form').addEventListener('submit', async (e) => {
e.preventDefault()
const formData = new FormData(e.target)
const data = Object.fromEntries(formData)
try {
const response = await fetch('https://jsonpost.com/api/submit/your-project-id/contact', {
method: 'POST',
headers: { "Content-Type": "application/json" },
body: JSON.stringify(data)
}
if (response.ok) {
alert('Message sent successfully!')
e.target.reset()
}
} catch (error) {
alert('Failed to send message')
}
}
</script>

Server-Side Form (SSR)

// src/pages/api/contact.ts
export async function POST({ request }) {
try {
const data = await request.json()
// Forward to JSONPost
const response = await fetch(
'https://jsonpost.com/api/submit/your-project-id/contact',
{
method: 'POST',
headers: { "Content-Type": "application/json" },
body: JSON.stringify(data)
}
)
if (response.ok) {
return new Response(JSON.stringify({ success: true }), {
status: 200,
headers: { "Content-Type": "application/json" }
}
}
throw new Error('Submission failed')
} catch (error) {
return new Response(JSON.stringify({ error: "Failed to submit" }), {
status: 500,
headers: { "Content-Type": "application/json" }
}
}
}
// src/components/SSRContactForm.astro
<form method="POST" action="/api/contact">
<input type="text" name="name" required />
<input type="email" name="email" required />
<textarea name="message" required></textarea>
<button type="submit">Send</button>
</form>

Configuration

Configure your Astro project for optimal JSONPost integration

// astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
output: 'hybrid', // For SSR pages
adapter: node(), // Or your preferred adapter
integrations: [
// Add any integrations you need
],
vite: {
define: {
'process.env.JSONPOST_ENDPOINT': JSON.stringify(
'https://jsonpost.com/api/submit/your-project-id'
)
}
}
}

File Uploads

Accept file uploads alongside your form data with automatic storage and management.

Enable File Uploads

Configure your endpoints to accept file uploads in your JSONPost dashboard

1

Navigate to endpoint settings

Go to your project dashboard and select the endpoint you want to configure.

2

Enable file uploads

Toggle the "File Uploads" option to allow file attachments.

3

Configure limits

Set maximum file size and allowed file types for security.

File Upload Limits

Understanding file size and type restrictions

Maximum File Size

Up to 10MB per file (Free tier)
Up to 50MB per file (Pro tier)
Up to 100MB per file (Enterprise tier)

Supported File Types

Images: JPG, PNG, GIF, WebP
Documents: PDF, DOC, DOCX, TXT
Archives: ZIP, RAR
And many more...

HTML Form with File Upload

Create a form that accepts both data and file uploads

<!-- HTML form with file upload -->
<form action="https://jsonpost.com/api/submit/your-project-id/contact"
method="POST" enctype="multipart/form-data">
<div>
<label for="name">Name:</label>
<input type="text" id="name" name="name" required>
</div>
<div>
<label for="email">Email:</label>
<input type="email" id="email" name="email" required>
</div>
<!-- File upload field -->
<div>
<label for="attachment">Attachment:</label>
<input type="file" id="attachment" name="attachment"
accept=".pdf,.doc,.docx,.jpg,.png" multiple>
</div>
<button type="submit">Submit with Files</button>
</form>

JavaScript File Upload

Upload files programmatically using JavaScript and FormData

// JavaScript file upload with FormData
const
uploadForm =
async
(formElement) => {
const
formData =
new
FormData(formElement);
// Add additional data if needed
formData.append(
'timestamp'
,
new
Date().toISOString());
try
{
const
response =
await
fetch(
'https://jsonpost.com/api/submit/your-project-id/contact',
{
method:
'POST'
,
// Don't set Content-Type header - let browser set it
body: formData
}
);
if
(response.ok) {
const
result =
await
response.json();
console.log(
'Upload successful:'
, result);
}
else
{
console.error(
'Upload failed'
);
}
}
catch
(error) {
console.error(
'Error:'
, error);
}
};
// Usage example
const
form = document.getElementById(
'upload-form'
);
form.addEventListener(
'submit'
, (e) => {
e.preventDefault();
uploadForm(form);
});

React File Upload Component

A complete React component for handling file uploads

import
React, { useState }
from
'react'
;
const
FileUploadForm = () => {
const
[files, setFiles] = useState(
null
);
const
[uploading, setUploading] = useState(
false
);
const
[message, setMessage] = useState(
''
);
const
handleSubmit =
async
(e) => {
e.preventDefault();
setUploading(
true
);
setMessage(
''
);
const
formData =
new
FormData(e.target);
try
{
const
response =
await
fetch(
'https://jsonpost.com/api/submit/your-project-id/contact',
{ method: 'POST', body: formData }
);
if
(response.ok) {
setMessage(
'Files uploaded successfully!'
);
e.target.reset();
setFiles(
null
);
}
else
{
setMessage(
'Upload failed. Please try again.'
);
}
}
catch
(error) {
setMessage(
'Error uploading files.'
);
}
finally
{
setUploading(
false
);
}
};
return
(
<form onSubmit={handleSubmit}>
<input type="text" name="name" placeholder="Your name" required />
<input type="email" name="email" placeholder="Your email" required />
<input
type="file"
name="files"
multiple
onChange={(e) => setFiles(e.target.files)}
/>
<button type="submit" disabled={uploading}>
{uploading ? 'Uploading...' : 'Submit'}
</button>
{message && <p>{message}</p>}
</form>
);
};
export default
FileUploadForm;

File Upload Best Practices

Tips for secure and efficient file uploads

Validate File Types

Always specify accepted file types using the `accept` attribute to prevent unwanted uploads.

Show Upload Progress

Provide visual feedback during uploads, especially for large files.

Handle Errors Gracefully

Implement proper error handling for file size limits, network issues, and unsupported formats.

Security Considerations

JSONPost automatically scans uploaded files for malware and enforces file type restrictions.

Webhooks

Receive real-time notifications when forms are submitted to your endpoints.

Webhook Configuration

Set up webhooks in your JSONPost dashboard to receive instant notifications

1

Navigate to your project dashboard

Go to your project settings and find the webhook configuration section.

2

Add your webhook URL

Enter the URL where you want to receive webhook notifications.

3

Test your webhook

Use the test feature to ensure your webhook endpoint is working correctly.

Webhook Payload

Example of the JSON payload sent to your webhook endpoint

{
"event": "form.submitted",
"timestamp": "2024-01-15T10:30:00Z",
"project_id": "abc123-def456",
"endpoint_path": "contact",
"submission_id": "sub_789xyz",
"data": {
"name": "John Doe",
"email": "john@example.com",
"message": "Hello from the form!"
},
"metadata": {
"ip_address": "192.168.1.1",
"user_agent": "Mozilla/5.0...",
"referer": "https://example.com/contact"
}
}

Webhook Security

Verify webhook authenticity with signature validation

// Node.js webhook verification example
const crypto = require('crypto')
function verifyWebhook(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex')
return crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(expectedSignature, 'hex')
)
}
// Express.js middleware
app.post('/webhook', (req, res) => {
const signature = req.headers['x-jsonpost-signature']
const payload = JSON.stringify(req.body)
if (verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
// Process the webhook
console.log('Valid webhook received:', req.body)
res.status(200).send('OK')
} else {
res.status(401).send('Unauthorized')
}
}

Email Notifications

Automatically send email notifications when forms are submitted.

Email Configuration

Set up email notifications in your JSONPost dashboard

Notification Types

  • Admin notifications (to you)
  • Auto-reply emails (to submitter)
  • Custom email templates
  • Multiple recipient support

Pro Tip: Use template variables like {name} and {email}to personalize your email notifications with form data.

Email Template Variables

Available variables for customizing your email templates

// Available template variables
{ form_data } // All submitted form data
{ submission_id } // Unique submission ID
{ timestamp } // Submission timestamp
{ ip_address } // Submitter's IP address
{ user_agent } // Browser information
{ referer } // Source page URL
// Example email template
Subject: New contact from { name }
Hello,
You received a new message from { name } ({ email })
Message: { message }
Submitted at: { timestamp }

JSON Schema Validation

Validate form submissions against custom JSON schemas to ensure data integrity and consistency.

How JSON Validation Works

JSONPost uses AJV (Another JSON Schema Validator) to validate incoming form submissions

When JSON validation is enabled for an endpoint, all incoming submissions are validated against your custom JSON schema before being stored. Invalid submissions are rejected with detailed error messages.

Validation Workflow:

  1. 1. Form submission received
  2. 2. JSON schema validation (if enabled)
  3. 3. Data stored in database (if valid)
  4. 4. Email notifications sent (if configured)
  5. 5. Webhooks triggered (if configured)

JSON Schema Example

Example schema for a contact form with validation rules

// Contact form JSON schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"email": {
"type": "string",
"format": "email"
},
"message": {
"type": "string",
"minLength": 10,
"maxLength": 1000
},
"age": {
"type": "integer",
"minimum": 13,
"maximum": 120
}
},
"required": ["name", "email", "message"],
"additionalProperties": false
}

Validation Error Handling

Understanding validation error responses and how to handle them

When validation fails, JSONPost returns a 400 Bad Request response with detailed error information:

// Example validation error response
{
"error": "Validation failed",
"details": [
{
"instancePath": "/email",
"schemaPath": "#/properties/email/format",
"keyword": "format",
"params": { "format": "email" },
"message": "must match format \"email\""
}
]
}

Frontend Handling: Parse the error details to show user-friendly validation messages in your form UI.

Best Practices

Tips for effective JSON schema validation

✅ Do

  • • Use descriptive property names
  • • Set appropriate min/max lengths
  • • Validate email formats
  • • Use required fields sparingly
  • • Test schemas thoroughly

❌ Don't

  • • Make schemas overly complex
  • • Use strict additionalProperties: false without consideration
  • • Forget to handle validation errors
  • • Skip schema testing
  • • Use unclear error messages

Schema Testing: Use online JSON schema validators to test your schemas before deploying them to production endpoints.

Security & Best Practices

Keep your forms secure with JSONPost's built-in security features.

Built-in Security Features

JSONPost includes comprehensive security measures by default

Rate limiting and spam protection
HTTPS encryption for all requests
Input validation and sanitization
CORS origins control
API key authentication
Webhook signature verification
IP-based access controls

Security Best Practices

Recommendations for secure form implementation

✅ Do

  • • Use HTTPS for your website
  • • Validate data on the frontend
  • • Implement CSRF protection
  • • Use descriptive endpoint paths
  • • Monitor submission patterns

❌ Don't

  • • Submit sensitive data without encryption
  • • Use predictable endpoint paths
  • • Ignore rate limiting warnings
  • • Store sensitive data in hidden fields
  • • Disable browser security features

CORS Origins Control

Restrict form submissions to specific domains for enhanced security

Configure allowed domains to prevent unauthorized cross-origin requests to your endpoints.

Configuration Options:

  • • https://example.com - Specific domain
  • • *.example.com - All subdomains
  • • * - All domains (not recommended)

Smart CORS Handling: Browser requests return the actual origin, while requests without an Origin header (like Postman or server-to-server calls) receive the first configured domain for security.

Best Practice: Always specify exact domains or use subdomain wildcards instead of allowing all origins.

API Key Authentication

Add an extra layer of security with API key verification

Enable API key authentication to ensure only authorized applications can submit to your endpoints.

# Include API key in headers
curl -X POST \
https://jsonpost.com/api/submit/your-project-id/contact \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"name": "John", "email": "john@example.com"}'

Security Note: Keep your API keys secure and regenerate them regularly. Never expose them in client-side code.

Secure JavaScript Integration

Examples of implementing security features in your frontend code

With API Key Authentication

// Secure form submission with API key
const
submitForm =
async
(formData) => {
const
response =
await
fetch(
'https://jsonpost.com/api/submit/your-project-id/contact',
{
method:
'POST'
,
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.NEXT_PUBLIC_JSONPOST_API_KEY
},
body: JSON.stringify(formData)
}
);
};

CORS-Compliant Requests

// Ensure your domain is in the allowed origins list
const
submitFromBrowser =
async
(data) => {
// This will work if your domain is allowed
const
response =
await
fetch(endpoint, {
method:
'POST'
,
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
});
};

Usage Limits & Billing

Understanding JSONPost's usage limits and billing tiers

300
Submissions per month (Free)
1,000
Submissions per month (Pro)
Unlimited
Submissions per month (Enterprise)

Usage Tracking: Your submission count is tracked monthly and resets at the beginning of each billing cycle. Upgrade your plan to increase your limits.

Ready to Get Started?

Create your free JSONPost account and start collecting form submissions in minutes.

Create Free Account View Dashboard
No credit card required • Free tier includes 300 submissions/month