Forms

Goal

Use a validated form configuration to create form instances, optionally attach files, and list/fetch results.

Prerequisites

1. Authenticate — Authentication
2. Build and create a configuration — Form configuration (POST /v0/forms/configurations/validate, then POST /v0/forms/configurations)
3. Optionally have a Space if you associate forms with Spaces

Configuration vs instance

	Form configuration	Form instance
Purpose	Defines pages, field types, validation, translations, capture flags	Holds one filled submission
Field identity	Structural key (e.g. p1_k1) + UUID id	Answers keyed by field id (UUID), not key
Copy / labels	Under translations via $ refs	Not re-sent; already on the configuration
Files	Declares file metadata (accept, maxBytes, …)	File fields are [] on create/update JSON; binaries via Media
Metadata	Flags: captureTimestamp, captureTags, …	Supply values under payload.metadata when those flags are enabled
Integrations	Flags: allowSpaceAssociations, allowWorkflowStarts	Supply spaceId / workflowConfigurationId under payload.integrations when allowed

There is no separate “extras” API step. When the configuration enables metadata or integrations, include them in the create/update payload (the web app collects them before summary; headless clients send the same JSON fields explicitly).

Steps

1. Note your configurationId (the configuration’s id)
2. POST /v0/forms — create an instance (see example below)
   • Include answers for non-file fields (keys = field UUIDs)
   • Set file fields to [] when the configuration defines them
   • Include metadata / integrations only for flags enabled on the configuration
   • Capture the returned formId
3. Optional files — Form with file (POST /v0/media/forms/{formId}/attachments)
4. GET /v0/forms/{formId} — fetch the instance (file fields return attachment descriptors, never storage paths)
5. GET /v0/forms — list instances (filter by configurationId, spaceId, states, pagination)
6. PATCH /v0/forms/{formId} — sparse update (same payload conventions; file fields stay [] here)

Example create payload

Aligned to the completed Form configuration template (configurationId and field UUIDs below). Adapt values and omit any metadata / integrations properties your configuration does not enable.

{
  "payload": {
    "configurationId": "12c8aa13-88f6-40de-b7c0-4b1bef48bb51",
    "language": "en",
    "fields": {
      "28837e41-7f0b-4f01-a2b1-794da82e124b": "North meadow",
      "d8c9eb00-3cb5-488c-8c1e-a0fa565212e2": "2026-08-14 10:30:00",
      "a1b2c3d4-e5f6-4a89-a012-3456789abcde": "open",
      "542abbf1-efc7-429e-9ca6-69d5d36f521a": "Soil moisture looks normal; minor weed pressure on the east edge.",
      "e4f5a6b7-c8d9-4e12-a345-67890abcdef0": []
    },
    "metadata": {
      "timestamp": 1723631400,
      "tags": "inspection,meadow,q3",
      "summary": "Routine field snapshot — north meadow.",
      "location": {
        "longitude": "-0.1276",
        "latitude": "51.5074",
        "altitude": "11"
      }
    },
    "integrations": {
      "spaceId": "YOUR_SPACE_ID",
      "workflowConfigurationId": "f8a3c2d1-4e5b-4a6f-9c8d-7e6f5a4b3c2d"
    }
  }
}

Payload area	Notes
fields	Map of field UUID → value. Dropdowns use the option value (e.g. open), not the option key. File fields must be [] until you upload via Media.
metadata.timestamp	Epoch seconds (or as accepted by the deployment) when captureTimestamp is true.
metadata.tags	Comma-separated string when captureTags is true.
metadata.summary	When captureSummary is true.
metadata.location	String coordinates when captureLocation is true.
integrations.spaceId	When allowSpaceAssociations is true.
integrations.workflowConfigurationId	When allowWorkflowStarts is true (must be allowlisted on that workflow config).

PATCH /v0/forms/{formId} uses the same payload wrapper; send only the slices you are changing.

Next

• Attachments: Form with file
• Review processes: Workflow configuration, Workflows

Exact payloads: API reference. Quotas: Errors & limits.