> ## Documentation Index > Fetch the complete documentation index at: https://docs.azalt.co/llms.txt > Use this file to discover all available pages before exploring further. # 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): ```json { "formId": "form-123", "format": "csv", "mode": "merge", "fileData": "" } ``` Example CSV content: ``` siteName,year,key,periodUnit,value,recordedAt plant-a,2024,water_usage,,120.5,2024-03-15T10:30:00Z ``` Example response (trimmed): ```json { "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. ## OpenAPI ````yaml https://app.azalt.co/api/v1/openapi.json post /form-element-submissions/import openapi: 3.0.3 info: title: Erguvan Public API version: 1.0.0 servers: - url: https://app.azalt.co/api/v1 security: [] paths: /form-element-submissions/import: post: tags: - FormElementSubmission summary: Import form element submissions description: >- 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): ```json { "formId": "form-123", "format": "csv", "mode": "merge", "fileData": "" } ``` Example CSV content: ``` siteName,year,key,periodUnit,value,recordedAt plant-a,2024,water_usage,,120.5,2024-03-15T10:30:00Z ``` Example response (trimmed): ```json { "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. operationId: importFormElementSubmissions requestBody: required: true content: application/json: schema: type: object properties: formId: type: string fileData: type: string format: type: string enum: - csv - xlsx default: csv mode: type: string enum: - merge - replace default: merge fileName: type: string minLength: 1 maxLength: 255 mediaId: type: string minLength: 1 required: - formId - fileData responses: '200': description: Successful response content: application/json: schema: type: object properties: success: type: boolean message: type: string stats: type: object properties: created: type: number updated: type: number deleted: type: number valuesDeleted: type: number formSitesCreated: type: number required: - created - updated - deleted - valuesDeleted - formSitesCreated required: - success - message - stats '400': description: Invalid input data content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' '401': description: Authorization not provided content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' '403': description: Insufficient access content: application/json: schema: $ref: '#/components/schemas/error.FORBIDDEN' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' security: - Authorization: [] components: schemas: error.BAD_REQUEST: type: object properties: message: type: string description: The error message example: Invalid input data code: type: string description: The error code example: BAD_REQUEST issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Invalid input data error (400) description: The error information example: code: BAD_REQUEST message: Invalid input data issues: [] error.UNAUTHORIZED: type: object properties: message: type: string description: The error message example: Authorization not provided code: type: string description: The error code example: UNAUTHORIZED issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Authorization not provided error (401) description: The error information example: code: UNAUTHORIZED message: Authorization not provided issues: [] error.FORBIDDEN: type: object properties: message: type: string description: The error message example: Insufficient access code: type: string description: The error code example: FORBIDDEN issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Insufficient access error (403) description: The error information example: code: FORBIDDEN message: Insufficient access issues: [] error.INTERNAL_SERVER_ERROR: type: object properties: message: type: string description: The error message example: Internal server error code: type: string description: The error code example: INTERNAL_SERVER_ERROR issues: type: array items: type: object properties: message: type: string required: - message description: An array of issues that were responsible for the error example: [] required: - message - code title: Internal server error error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: Internal server error issues: [] securitySchemes: Authorization: type: http scheme: bearer ````