> ## 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. # Get form submissions > Retrieve form submissions with flexible identification options: **Form Identification** (choose one): - `formId`: Direct form ID (e.g., "form-abc123") - `formMetadataKey` + `formMetadataValue`: Lookup by metadata (e.g., "erpFormId" = "form123") **Optional Site Filtering**: - `siteId`: Filter by specific site ID - `siteMetadataKey` + `siteMetadataValue`: Filter by site metadata - `year`: Filter by specific year You can identify forms using either internal IDs or custom metadata key-value pairs, making it easy to integrate with external systems. Response shape notes: - Each submission contains `values` grouped by (elementId, periodUnit). - When a cell has multiple entries (e.g., TIMESTAMP elements with multiple timepoints in the same month, or ACTIVITY outputs), `value` becomes an array. Each array item includes: - `recordedAt` (for TIMESTAMP entries), - `formElementSubmissionId`, `status`, and `docs` (supporting documents) for that specific row. - For single entries, `value` is the scalar value. Example response (trimmed): ```json [ { "id": "fs-1", "year": 2024, "values": [ { "elementId": "el-monthly", "periodUnit": 3, "value": 120.5, "status": "APPROVED" }, { "elementId": "el-ts", "periodUnit": 3, "value": [ { "value": 10, "recordedAt": "2024-03-05T10:30:00Z", "formElementSubmissionId": "fes-1", "status": "COMPLETED", "docs": [] }, { "value": 15, "recordedAt": "2024-03-12T08:00:00Z", "formElementSubmissionId": "fes-2", "status": "APPROVED", "docs": [] } ] } ] } ] ``` ## OpenAPI ````yaml https://app.azalt.co/api/v1/openapi.json get /form-submissions openapi: 3.0.3 info: title: Erguvan Public API version: 1.0.0 servers: - url: https://app.azalt.co/api/v1 security: [] paths: /form-submissions: get: tags: - FormSubmission summary: Get form submissions description: > Retrieve form submissions with flexible identification options: **Form Identification** (choose one): - `formId`: Direct form ID (e.g., "form-abc123") - `formMetadataKey` + `formMetadataValue`: Lookup by metadata (e.g., "erpFormId" = "form123") **Optional Site Filtering**: - `siteId`: Filter by specific site ID - `siteMetadataKey` + `siteMetadataValue`: Filter by site metadata - `year`: Filter by specific year You can identify forms using either internal IDs or custom metadata key-value pairs, making it easy to integrate with external systems. Response shape notes: - Each submission contains `values` grouped by (elementId, periodUnit). - When a cell has multiple entries (e.g., TIMESTAMP elements with multiple timepoints in the same month, or ACTIVITY outputs), `value` becomes an array. Each array item includes: - `recordedAt` (for TIMESTAMP entries), - `formElementSubmissionId`, `status`, and `docs` (supporting documents) for that specific row. - For single entries, `value` is the scalar value. Example response (trimmed): ```json [ { "id": "fs-1", "year": 2024, "values": [ { "elementId": "el-monthly", "periodUnit": 3, "value": 120.5, "status": "APPROVED" }, { "elementId": "el-ts", "periodUnit": 3, "value": [ { "value": 10, "recordedAt": "2024-03-05T10:30:00Z", "formElementSubmissionId": "fes-1", "status": "COMPLETED", "docs": [] }, { "value": 15, "recordedAt": "2024-03-12T08:00:00Z", "formElementSubmissionId": "fes-2", "status": "APPROVED", "docs": [] } ] } ] } ] ``` operationId: getFormSubmissions parameters: - in: query name: formId schema: type: string - in: query name: formMetadataKey schema: type: string - in: query name: formMetadataValue schema: type: string - in: query name: siteId schema: type: string nullable: true required: true - in: query name: siteMetadataKey schema: type: string - in: query name: siteMetadataValue schema: type: string - in: query name: year schema: type: number nullable: true required: true - in: query name: activityValueMode schema: type: string enum: - full - summary responses: '200': description: Successful response content: application/json: schema: type: array items: type: object properties: id: type: string formSiteId: type: string organizationId: type: string nullable: true userId: type: string nullable: true userName: type: string nullable: true userEmail: type: string nullable: true submitterName: type: string nullable: true submitterEmail: type: string nullable: true submitterTitle: type: string nullable: true submitterCompany: type: string nullable: true submitterAddress: type: string nullable: true createdAt: type: string updatedAt: type: string year: type: number values: type: array items: type: object properties: formElementSubmissionId: type: string elementId: type: string value: {} originalValue: nullable: true periodUnit: type: number selectedUnitId: type: string nullable: true status: type: string enum: - COMPLETED - APPROVED - REJECTED userId: type: string nullable: true userName: type: string nullable: true userEmail: type: string nullable: true userImage: type: string nullable: true docs: type: array items: {} comments: type: array items: {} recordedAt: type: string required: - formElementSubmissionId - elementId - periodUnit - status draftFiles: type: array items: {} deletedAt: type: string nullable: true score: type: number nullable: true scoreBreakdown: nullable: true actionPlan: type: string nullable: true required: - id - formSiteId - organizationId - userId - userName - userEmail - submitterName - submitterEmail - submitterTitle - submitterCompany - submitterAddress - createdAt - updatedAt - year - values - deletedAt - score - actionPlan '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' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/error.NOT_FOUND' '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.NOT_FOUND: type: object properties: message: type: string description: The error message example: Not found code: type: string description: The error code example: NOT_FOUND 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: Not found error (404) description: The error information example: code: NOT_FOUND message: Not found 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 ````