Import form element submissions

curl --request POST \
  --url https://app.azalt.co/api/v1/form-element-submissions/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "formId": "<string>",
  "fileData": "<string>",
  "format": "csv",
  "mode": "merge",
  "fileName": "<string>",
  "mediaId": "<string>"
}
'

{
  "success": true,
  "message": "<string>",
  "stats": {
    "created": 123,
    "updated": 123,
    "deleted": 123,
    "valuesDeleted": 123,
    "formSitesCreated": 123
  }
}

FormElementSubmission

Import form element submissions

Import form element submissions data from external sources in bulk.

Import Features:

Bulk data import from structured formats (CSV, Excel, JSON)
Validation and error reporting for imported data
Support for both new submissions and updates to existing ones
Flexible mapping between external data formats and internal form structure

Data Validation:

Validates form element types and constraints
Ensures data integrity and consistency
Provides detailed error reports for failed imports
Supports rollback mechanisms for failed batch operations

TIMESTAMP support:

Accepts a recordedAt (or timestamp) column; required for TIMESTAMP elements.
Parses ISO 8601 (assumes UTC if timezone missing), validates that year matches the CSV year, and derives periodUnit from the UTC month.
Upserts per (formSubmissionId/new_formSiteId, formElementId, recordedAt); duplicates by timestamp update the value; empty value with recordedAt deletes that exact entry in replace mode and is ignored in merge mode.

Import modes:

merge: updates values present in the file and leaves omitted values unchanged.
replace: updates values present in the file and clears omitted values in the imported form/site/year scope.

Multi-form import:

If the uploaded file contains a formName column (as produced by the export when includeFormName=true), rows are routed to their respective forms by name. In this case, formId in the request is ignored for those rows.
When formName is not present, the import behaves as single-form and uses the provided formId.

Example request (CSV import, trimmed):

{
  "formId": "form-123",
  "format": "csv",
  "mode": "merge",
  "fileData": "<base64-csv>"
}

Example CSV content:

siteName,year,key,periodUnit,value,recordedAt
plant-a,2024,water_usage,,120.5,2024-03-15T10:30:00Z

Example response (trimmed):

{
  "success": true,
  "message": "Imported",
  "stats": { "created": 1, "updated": 0, "deleted": 0, "valuesDeleted": 0, "formSitesCreated": 0 }
}

This endpoint is essential for migrating data from legacy systems, bulk data entry operations, and automated data synchronization workflows.

POST

form-element-submissions

import

Import form element submissions

curl --request POST \
  --url https://app.azalt.co/api/v1/form-element-submissions/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "formId": "<string>",
  "fileData": "<string>",
  "format": "csv",
  "mode": "merge",
  "fileName": "<string>",
  "mediaId": "<string>"
}
'

{
  "success": true,
  "message": "<string>",
  "stats": {
    "created": 123,
    "updated": 123,
    "deleted": 123,
    "valuesDeleted": 123,
    "formSitesCreated": 123
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

formId

string

required

fileData

string

required

format

enum<string>

default:csv

Available options:

csv,

xlsx

mode

enum<string>

default:merge

Available options:

merge,

replace

fileName

string

Required string length: 1 - 255

mediaId

string

Minimum string length: 1

Response

Successful response

success

boolean

required

message

string

required

stats

object

required

Show child attributes

Export form element submissions Preview form element submissions import