# Submissions

Operations related to form submissions

## GET /api/submission

> Get submissions list

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission":{"get":{"operationId":"SubmissionController_getAllSubmissions","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"perPage","required":false,"in":"query","description":"Items per page (default: 10)","schema":{"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field (default: createdAt)","schema":{"enum":["createdAt","updatedAt"],"type":"string"}},{"name":"sortDir","required":false,"in":"query","description":"Sort direction (default: desc)","schema":{"enum":["asc","desc"],"type":"string"}},{"name":"status","required":false,"in":"query","description":"Comma-separated list of statuses to filter by","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a paginated list of submissions"}},"summary":"Get submissions list","tags":["Submissions"]}}}}
```

## POST /api/submission

> Create a new submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"CreateSubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"name":{"type":"string","description":"Submission name"},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"}}},"SubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"submissionNumber":{"type":"number","description":"Submission sequence number"},"name":{"type":"string","description":"Submission name"},"template":{"description":"Associated template","allOf":[{"$ref":"#/components/schemas/Template"}]},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"files":{"description":"Files attached to the submission","type":"array","items":{"type":"string"}},"status":{"description":"Current status of the submission","allOf":[{"$ref":"#/components/schemas/SubmissionStatus"}]},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"},"OBEExtraction":{"type":"string","description":"ID of the old backend extraction event"},"NBEExtraction":{"type":"string","description":"ID of the new backend extraction event"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was last updated"}},"required":["id","submissionNumber","name","template","templateId","files","status","createdAt","updatedAt"]},"Template":{"type":"object","properties":{"id":{"type":"number","description":"The ID of the template"},"templateId":{"type":"string","description":"The UUID of the template"},"name":{"type":"string","description":"The name of the template"},"description":{"type":"string","description":"The description of the template"},"version":{"type":"number","description":"The version of the template"},"schema":{"type":"object","description":"The schema of the template"},"vendorSchemaName":{"type":"string","description":"The vendor schema name"},"vendorSchemaVersion":{"type":"number","description":"The vendor schema version"},"vendorSchema":{"type":"object","description":"The vendor schema"},"dereferencedVendorSchema":{"type":"object","description":"The dereferenced vendor schema with resolved $ref references"},"aiGenerated":{"type":"boolean","description":"Whether the template was generated using AI"},"emailAlias":{"type":"string","description":"The email alias"},"extractionStrategyId":{"type":"string","description":"The uuid of extraction strategy template uses."},"extractionStrategy":{"description":"Associated extraction strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"referenceStrategy":{"description":"Associated reference strategy","allOf":[{"$ref":"#/components/schemas/Strategy"}]},"state":{"type":"string","description":"The state of the template","enum":["draft","published"],"default":"published"},"parsingInstructions":{"type":"object","description":"the parsing instructions for a template"}},"required":["id","templateId","name","version","aiGenerated","extractionStrategyId","extractionStrategy","referenceStrategy","state","parsingInstructions"]},"Strategy":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the strategy"},"identifier":{"type":"string","description":"Identifier of the strategy type","enum":["extraction-claude-3-7","extraction-gemini-2-5-loose","extraction-claude-3-7-thinking","extraction-atomic"]},"type":{"type":"string","description":"Type of the strategy","default":"extraction"},"displayName":{"type":"string","description":"Display name of the strategy"},"description":{"type":"string","description":"Description of the strategy"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the strategy was last updated"}},"required":["id","identifier","type","displayName","createdAt","updatedAt"]},"SubmissionStatus":{"type":"string","enum":["created","processing","processing-failed","processed","in-review","completed","exported","export-failed","discarded","preparing","queued"]}}},"paths":{"/api/submission":{"post":{"operationId":"SubmissionController_createSubmission","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubmissionDto"}}}},"responses":{"201":{"description":"The submission has been successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionDto"}}}}},"summary":"Create a new submission","tags":["Submissions"]}}}}
```

## GET /api/submission/{id}

> Get submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission/{id}":{"get":{"operationId":"SubmissionController_getSubmissionById","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"summary":"Get submission","tags":["Submissions"]}}}}
```

## PATCH /api/submission/{id}

> Update submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"UpdateSubmissionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the submission"},"submissionNumber":{"type":"number","description":"Submission sequence number"},"name":{"type":"string","description":"Submission name"},"templateId":{"type":"number","description":"ID of the associated template"},"uploaderUserId":{"type":"string","description":"ID of the user who uploaded the submission"},"userId":{"type":"string","description":"ID of the user associated with the submission"},"status":{"description":"Current status of the submission","allOf":[{"$ref":"#/components/schemas/SubmissionStatus"}]},"emailSender":{"type":"string","description":"Email address of the sender"},"emailBody":{"type":"string","description":"Email body or additional context"},"emailMessageId":{"type":"string","description":"Email message ID"},"payload":{"type":"object","description":"Submission payload data"},"manualPayload":{"type":"object","description":"Manual payload data"},"metaPayload":{"type":"object","description":"Metadata payload"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the submission was last updated"}}},"SubmissionStatus":{"type":"string","enum":["created","processing","processing-failed","processed","in-review","completed","exported","export-failed","discarded","preparing","queued"]}}},"paths":{"/api/submission/{id}":{"patch":{"operationId":"SubmissionController_updateSubmission","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubmissionDto"}}}},"responses":{"200":{"description":"The submission has been successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubmissionDto"}}}}},"summary":"Update submission","tags":["Submissions"]}}}}
```

## GET /api/submission/{id}/references

> Get references for submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission/{id}/references":{"get":{"operationId":"SubmissionController_getSubmissionReferences","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns references for a specific submission"}},"summary":"Get references for submission","tags":["Submissions"]}}}}
```

## GET /api/submission/{id}/events

> Get all events for a submission

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"Event":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the event"},"submissionId":{"type":"string","description":"Related submission ID","nullable":true},"type":{"type":"string","description":"Type of event","enum":["upload","email","conversion","extraction","export","discard","reference","generate-schema","metadata"]},"state":{"type":"string","description":"Current state of the event","enum":["pending","succeed","fail"]},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the event was created"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the event was last updated"}},"required":["id","submissionId","type","state","createdAt","updatedAt"]}}},"paths":{"/api/submission/{id}/events":{"get":{"operationId":"SubmissionController_getSubmissionEvents","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID to retrieve events for","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns all events and their current status for the specified submission","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}},"404":{"description":"Submission with ID 123e4567-e89b-12d3-a456-426614174001 not found"}},"summary":"Get all events for a submission","tags":["Submissions"]}}}}
```

## POST /api/submission/{id}/upload

> Get temporary S3 URL for client-side upload

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{},"schemas":{"UploadRequestDto":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file to upload"},"contentType":{"type":"string","description":"MIME type of the file"}},"required":["fileName","contentType"]}}},"paths":{"/api/submission/{id}/upload":{"post":{"operationId":"SubmissionController_getUploadUrl","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Upload file details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequestDto"}}}},"responses":{"201":{"description":""}},"summary":"Get temporary S3 URL for client-side upload","tags":["Submissions"]}}}}
```

## POST /api/submission/{id}/export

> Export submission to ledger

```json
{"openapi":"3.0.0","info":{"title":"Formflow API","version":"1.0"},"tags":[{"name":"Submissions","description":"Operations related to form submissions"}],"security":[{"access-token":[]}],"components":{"securitySchemes":{}},"paths":{"/api/submission/{id}/export":{"post":{"operationId":"SubmissionController_exportSubmission","parameters":[{"name":"id","required":true,"in":"path","description":"Submission ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Submission successfully exported"},"404":{"description":"Submission not found"},"500":{"description":"Export failed"}},"summary":"Export submission to ledger","tags":["Submissions"]}}}}
```