Upsert form submission

Create or update a form submission. You have flexible options for identifying forms, sites, and form elements:

Form Identification (choose one):

• formId: Direct form ID (e.g., “form-abc123”)
• formMetadataKey + formMetadataValue: Lookup by metadata (e.g., “erpFormId” = “form123”)

Site Identification (choose one):

• siteId: Direct site ID (e.g., “site-xyz789”)
• siteMetadataKey + siteMetadataValue: Lookup by metadata (e.g., “erpSiteId” = “123”)

Form Element Identification (choose one per element):

• elementId: Direct element ID (e.g., “formel-def456”)
• elementKey: Element key within the form (e.g., “energy_consumption”)
• elementMetadataKey + elementMetadataValue: Lookup by metadata (e.g., “extId” = “ext01”)

TIMESTAMP elements:

• Provide values[].timestamp (ISO 8601). The server requires it for TIMESTAMP elements, derives periodUnit from the UTC month, and validates that the timestamp year matches the submission year.
• Upsert semantics: entries are de-duplicated by (formSubmissionId, formElementId, recordedAt). Sending the same timestamp updates the existing entry; otherwise, a new entry is inserted.
• To delete a TIMESTAMP entry, send value: null with the same timestamp.

Example request (TIMESTAMP):

{
  "formId": "form-123",
  "siteId": "site-1",
  "year": 2024,
  "values": [
    { "elementId": "el-ts", "value": 42, "timestamp": "2024-03-15T10:30:00Z", "periodUnit": 3 }
  ]
}

Example response (trimmed):

{
  "id": "fs-1",
  "formSiteId": "fs-site-1",
  "values": [
    { "elementId": "el-ts", "periodUnit": 3, "value": 42, "recordedAt": "2024-03-15T10:30:00.000Z" }
  ]
}

This flexibility allows integration with external systems using their own IDs via metadata, while also supporting direct internal ID references.