Documentation/Developer API
Developer API

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

  1. Open Developers in your workspace.
  2. Give the key a name and select Create key.
  3. 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_KEY

List submissions

GET https://formpostbox.com/api/v1/submissions

Query 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 as 2026-10-08T09:30:00Z. from is inclusive; to is exclusive. A date-only to covers the whole UTC day.
  • limit — page size from 1 to 100. Default 25.
  • cursor — opaque value from nextCursor. 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

StatusCodeMeaning
400invalid_request / invalid_cursorA parameter or filter context is invalid, or the cursor is malformed or was issued for different filters.
401invalid_keyMissing, malformed, revoked, or expired key, or a closed account.
403plan_requiredThe workspace has no current paid entitlement.
404not_foundUnknown route, or a record that is missing, outside your workspace, or past its retention date.
405method_not_allowedOnly GET is supported. The response carries Allow: GET.
429rate_limitToo many requests. Read Retry-After and wait.
503unavailableA 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 ↑