Using the REST API

A webhook pushes a submission to you the second it lands. The REST API works the other way round: your code asks when it suits — a nightly job pulling yesterday's callout reports into a rota system, a script that spins up a fresh intake form per client.

Everything sits under https://app.formformform.com. Authentication is a bearer token you fetch by signing in over the API; there is no API-key screen in Settings, and the token reaches as far as your account does. Resources come back wrapped in a data key.

You exchange your account password for a token once, then send that token on every later call. Nothing expires on a timer, so a token left in a cron job keeps working until POST /api/v1/auth/logout revokes it — and that call revokes only the token that made it.

Under /api/v1, with your token: forms (list, create, read, update, delete, plus /duplicate and /toggle-active), a form's fields (create, update, delete, reorder), submissions (list, read, delete, export), and /api/v1/templates. Under /api/v1/public, with no token: read an active form and post an answer to it.

Which identifier goes where is what trips people up. A form is addressed by its uuid, already in the editor's address bar at /form-builder/<uuid>/edit, and a submission by its own uuid. Fields are the exception, taking the integer id the API hands back. Public routes use a third value, the short public_id from the share link.

GET /api/v1/forms/<uuid>/submissions returns newest first, 25 to a page, per_page adjustable up to 100, with today_count alongside. Each row holds uuid, created_at, ip_address, user_agent and a values array — one entry per answered field, giving field_uuid, field_type, field_label and value. Fields left blank or hidden by conditional logic are absent rather than null, so read by field_uuid, never by position.

Fetching one submission adds prev and next uuids for walking the list, plus the armoured encrypted_payload on an encrypted form. /submissions/export streams the same CSV as the Submissions tab: a column per input field, then Submitted At, IP Address, Filled At and Was Offline.

GET /api/f/<public_id> returns the live form: title, thank-you message, and every field with its integer id, type, options and is_required flag. POST back to the same address with a fields object keyed by those ids. The reply carries submission_uuid plus the thank-you message and any redirect. Throttled at 30 posts a minute per IP.

A file goes up on its own, before the submission exists. POST it as multipart to /f/<public_id>/uploads with form_field_id set to the File Upload field, read the uuid from the reply, then send that uuid twice: as the field's value inside fields, and in the upload_uuids array. Up to 50 files per submission. An encrypted form takes an armoured encrypted_payload in place of fields.