API Documentation

Complete guide to integrating with apiforms

Start with 100 free submissions

Quick Start

apiforms lets you collect form submissions without building backend infrastructure. Create forms, get an endpoint, and start collecting data in minutes.

Sign Up & Create Forms

Create your account and set up your forms from the dashboard.

Design Visually

Use the live designer to style your form. Changes sync to all embeds automatically.

Embed or Submit via API

Paste the HTML snippet on your site, use the generated React component, or POST directly to the API.

Submit Form API

Use this endpoint to submit data to your forms. Requires a valid Form ID and an active subscription.

POSThttps://apiforms.com/api/forms/submit

Authentication

No API key is required. Just include your formId in the request body.

Headers

Content-Type: application/json

Request Body

JSON Payload

{
  "formId": "YOUR_FORM_ID",
  "formData": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello from Forms API!"
  }
}

Note: Replace YOUR_FORM_ID with your actual Form ID from the dashboard.

Response (Success)

200 OK

{
  "success": true,
  "remaining": 19
}

The remaining field shows how many submissions you have left in your current billing period.

Field Validation

The API enforces your form's schema server-side. A required field is rejected if its value is null, undefined, a whitespace-only string, or an empty array. For select and radio fields, the submitted value must match one of the field's defined options. Validation failures return a 400 with an array of error messages:

400 Validation Error

{
  "error": ["Name is required", "Plan must be one of Free, Pro, Enterprise"]
}

Error Handling

Error Response Format

Error Examples

// 400 - Bad Request
{ "error": "Missing fields" }

{ "error": ["Name is required", "Plan must be one of Free, Pro, Enterprise"] }

// 403 - Forbidden
{ "error": "This form is not currently accepting submissions.", "code": "SUBSCRIPTION_REQUIRED" }

{ "error": "This form restricts submissions to specific origins. Add your domain in the form settings.", "code": "ORIGIN_DENIED" }

{ "error": "Origin not allowed", "code": "ORIGIN_DENIED" }

{ "error": "Invalid origin", "code": "ORIGIN_DENIED" }

// 404 - Not Found
{ "error": "Form not found" }

// 410 - Gone
{ "error": "This form is no longer accepting submissions", "code": "FORM_ARCHIVED" }

// 429 - Too Many Requests
{ "error": "Submission limit exceeded (100). Upgrade your plan for more.", "code": "SUBSCRIPTION_LIMIT_EXCEEDED" }

{ "error": "Too many requests" }

// 500 - Internal Server Error
{ "error": "Server error" }

HTTP Status Codes

Code	Description
200	Success - Form submitted successfully
400	Bad Request - Missing fields or validation failed
403	Forbidden - Subscription inactive or origin denied
404	Not Found - Form not found
410	Gone - Form is archived
429	Too Many Requests - Rate limit or submission limit exceeded
500	Internal Server Error - Server error

Implementation Examples

cURL

Basic cURL Request

curl -X POST https://apiforms.com/api/forms/submit \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "YOUR_FORM_ID",
    "formData": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "Hello from Forms API!"
    }
  }'

JavaScript (Node.js/Browser)

Using fetch()

const response = await fetch("https://apiforms.com/api/forms/submit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    formId: "YOUR_FORM_ID",
    formData: {
      name: "John Doe",
      email: "john@example.com",
      message: "Hello from Forms API!"
    }
  })
});

const result = await response.json();
console.log(result);

Python

Using requests library

import requests

response = requests.post("https://apiforms.com/api/forms/submit", json={
    "formId": "YOUR_FORM_ID",
    "formData": {
        "name": "John Doe",
        "email": "john@example.com",
        "message": "Hello from Forms API!"
    }
})

result = response.json()
print(result)

PHP

Using cURL in PHP

<?php
$url = 'https://apiforms.com/api/forms/submit';
$data = [
    'formId' => 'YOUR_FORM_ID',
    'formData' => [
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'message' => 'Hello from Forms API!'
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);

echo json_encode($result, JSON_PRETTY_PRINT);
curl_close($ch);
?>

Need Help?

If you need help integrating or have questions about advanced features, get in touch — happy to help.