Read submissions from your servers
The Developer API is a read-only interface for your own servers, scripts and tools. It returns submissions your workspace already received and that are still inside their retention period. API requests never use your submission allowance and never change review or notification state.
Which plans include it
An active Starter or Builder plan includes the Developer API. Free does not: API access is a paid capability.
Every request re-checks your current paid period. If you cancel renewal, access continues until the period you already paid for ends, then stops. Keys that are still active work again if a paid plan is restored; keys that were revoked, expired, or invalidated by a password change stay unusable.
Create and manage keys
- Open Developers in your workspace.
- Give the key a name and select Create key.
- Copy the full key immediately. It is displayed once and cannot be shown again — afterwards only its name, hint, and dates remain listed.
Each workspace can hold up to 10 active keys, and a key expires automatically 365 days after creation. To rotate, create a new key, update your server, then revoke the old one. Revocation takes effect immediately across every server. Changing or resetting your password revokes all keys, closing the account revokes them and blocks them instantly, and a backup restore invalidates every previously issued key.
Authentication
Send the key as a Bearer token on every request. The key is bound to one workspace and a fixed read-only scope (submissions:read). It cannot create, change, or delete anything, and it never works on browser or admin endpoints.
Authorization: Bearer YOUR_API_KEYList submissions
GET https://formpostbox.com/api/v1/submissionsQuery parameters:
formId— restrict results to one form (UUID).from/to— UTC time bounds. Use a calendar date (YYYY-MM-DD) or a UTC timestamp such as2026-10-08T09:30:00Z.fromis inclusive;tois exclusive. A date-onlytocovers the whole UTC day.limit— page size from 1 to 100. Default 25.cursor— opaque value fromnextCursor. Keep the same filters while paging; a cursor is rejected if filters change.
Each listed item contains id, formId, formName, siteName, receivedAt and retentionEndsAt (UTC ISO 8601), reviewed, notificationStatus, and a truncated summary (title, preview). The summary is a preview only — request the detail endpoint for the complete submitted fields.
{
"data": [
{
"id": "b1f0c2f4-…",
"formId": "7f3c5b12-…",
"formName": "Contact form",
"siteName": "northstar.example",
"receivedAt": "2026-10-08T09:30:00.000Z",
"retentionEndsAt": "2027-10-08T09:30:00.000Z",
"reviewed": false,
"notificationStatus": "delivered",
"summary": { "title": "Question about pricing", "preview": "Hi, I would like to know…" }
}
],
"hasMore": false,
"nextCursor": null
}Submission detail
GET https://formpostbox.com/api/v1/submissions/{submissionId}The detail response adds the complete fields object exactly as submitted. Deleted records, cleared content, records past their deletion date, and closed accounts are never returned; a lookup outside your workspace answers 404, exactly like a missing record.
Example: curl
curl -s "https://formpostbox.com/api/v1/submissions?limit=25&from=2026-10-01" \
-H "Authorization: Bearer YOUR_API_KEY"Example: server-side JavaScript
const apiKey = process.env.FORMPOSTBOX_API_KEY;
export async function listSubmissions(formId) {
const url = new URL('https://formpostbox.com/api/v1/submissions');
url.searchParams.set('formId', formId);
url.searchParams.set('limit', '100');
const response = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (!response.ok) {
const { code } = await response.json();
throw new Error(`Developer API error ${response.status}: ${code}`);
}
return response.json();
}Read every page
The listSubmissions example above reads one page only. Return nextCursor until hasMore is false, keeping the filters unchanged. Do not construct or decode cursors yourself. This async iterator reads sequential pages; if a request returns 429, wait for Retry-After before trying again and avoid parallel retries.
const apiKey = process.env.FORMPOSTBOX_API_KEY;
async function* allSubmissions(formId) {
let cursor;
do {
const url = new URL('https://formpostbox.com/api/v1/submissions');
url.searchParams.set('formId', formId);
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('cursor', cursor);
const response = await fetch(url, {headers: {Authorization: `Bearer ${apiKey}`}});
if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get('Retry-After')}`);
const page = await response.json();
yield* page.data;
cursor = page.hasMore ? page.nextCursor : null;
} while (cursor);
}
for await (const submission of allSubmissions('YOUR_FORM_ID')) {
console.log(submission.id);
}Date example: from=2026-10-01&to=2026-10-16 includes all of October 16 in UTC, while to=2026-10-16T00:00:00Z excludes that instant and later records. Download the OpenAPI YAML.
Rate limits
- 60 requests per minute per workspace, shared by all of its keys.
- 30 requests per minute per key. Creating more keys does not raise the workspace limit.
- Creating keys, listing them, and revoking them have their own limits in the workspace.
When a limit is reached, the API answers 429 with a Retry-After header (seconds). Wait at least that long before retrying, and avoid parallel retry bursts.
Status codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request / invalid_cursor | A parameter or filter context is invalid, or the cursor is malformed or was issued for different filters. |
| 401 | invalid_key | Missing, malformed, revoked, or expired key, or a closed account. |
| 403 | plan_required | The workspace has no current paid entitlement. |
| 404 | not_found | Unknown route, or a record that is missing, outside your workspace, or past its retention date. |
| 405 | method_not_allowed | Only GET is supported. The response carries Allow: GET. |
| 429 | rate_limit | Too many requests. Read Retry-After and wait. |
| 503 | unavailable | A temporary condition or resource contention. Retry later. |
Error bodies are JSON: { "error": "…", "code": "…" }. Every response, including errors, uses Cache-Control: no-store. Error responses never echo SQL, credentials, message content or internal errors; successful detail responses return authorized submission fields.
Retention and lifecycle
The API shows exactly what the app shows: a record disappears at its own deletion date, and upgrading cannot bring deleted or expired content back. Keys expire after 365 days and cannot be re-enabled once revoked, expired, or invalidated by a password change.
Keep the key secret
Use API keys only from trusted servers you control. Never embed a key in public web pages, browser bundles, distributed apps, or public repositories — anyone holding the key can read this workspace’s retained submissions. If a key leaks, revoke it in Developers and create a replacement.
Still need help? Contact support@formpostbox.com. Include the guide topic and redacted error details, without keys or visitor messages.
Browse all topics ↑