API reference
Public API
Submit from your own server with a private key, under /api/v1.
Basics
| Base URL | https://api.inputdock.com. |
| Format | JSON. Send Accept: application/json. Submissions can be sent as JSON (Content-Type: application/json) or as a regular form body. |
| Every response | Has a leading success boolean: true for 2xx and 3xx, false for 4xx and 5xx. Successful bodies carry data; failed ones carry message and, for validation, errors. |
| Authentication | Requests take the private key in the X-Form-Key header. Nothing else is needed. |
Keep the private key on your server. Anyone holding it can post to the form. If it leaks, rotate it in the form’s Settings; the old one stops working.
Submit from your server
POST/api/v1/form/submit
Use this from backend code, for example to forward a form you render yourself. Authenticate with the private key in X-Form-Key. Send one property per field, named after the field’s name. Fields that are hidden by a condition are ignored, and so is anything that is not in the form.
curl -X POST https://api.inputdock.com/api/v1/form/submit \
-H "Accept: application/json" \
-H "X-Form-Key: your_private_key" \
-d "name=Maya Patel" \
-d "[email protected]" \
-d "message=Hello from my backend"// Node 18+, runs on your server only
const response = await fetch('https://api.inputdock.com/api/v1/form/submit', {
method: 'POST',
headers: {
Accept: 'application/json',
'Content-Type': 'application/json',
'X-Form-Key': process.env.INPUTDOCK_PRIVATE_KEY,
},
body: JSON.stringify({ name: 'Maya Patel', email: '[email protected]', message: 'Hello!' }),
})
const result = await response.json()
if (!result.success) throw new Error(result.message)
console.log('Saved submission', result.data.id)<?php
$ch = curl_init('https://api.inputdock.com/api/v1/form/submit');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Accept: application/json', 'X-Form-Key: ' . getenv('INPUTDOCK_PRIVATE_KEY')],
CURLOPT_POSTFIELDS => http_build_query(['name' => 'Maya Patel', 'email' => '[email protected]', 'message' => 'Hello!']),
]);
$result = json_decode(curl_exec($ch), true);
if (!($result['success'] ?? false)) { /* handle $result['message'] */ }{
"success": true,
"data": { "id": "9b2e4c1a-5f3d-4e8a-b7c6-2d1f0a8e3c45" }
}{
"success": false,
"message": "The email field must be a valid email address.",
"errors": {
"email": ["The email field must be a valid email address."]
}
}Responses: 201 with { "data": { "id" } }, 401 for a bad key, 404 when the form is inactive or expired, 422 for validation.
What gets stored
Each validated answer is saved with its label, along with the visitor’s IP address and browser. In the dashboard a submission shows the sender (the person’s name from the form, or “Anonymous”), their email and phone when the form asks for them, every answer, and the history of that person across your forms.
New-submission emails go to the email address in the client’s info and name the form only. Answers are never emailed.
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid X-Form-Key. |
403 | The form lists allowed websites and the request’s Origin is not one of them. |
404 | Unknown public key, or the form is inactive or its subscription has expired. |
413 | The body is larger than 64 KB. |
422 | Validation failed. errors maps each field name to its messages. |
429 | Rate limit hit. Wait for the time in the Retry-After header. |
5xx | Something went wrong on our side. Retry with backoff. |
Rate limits
| Endpoint | Limit |
|---|---|
POST /api/v1/embed/…/submit | 10 per minute per IP address and form; 1,000 per day per form |
POST /api/v1/form/submit | 30 per minute |
Hitting a limit returns 429 with a Retry-After header. If your site sits behind a proxy or load balancer, make sure the API sees the visitor’s real IP address, otherwise all visitors share one bucket.