Process a submission via API

This guide explains how to process a submission using the FormFlow API.

The sequence involves creating a submission, uploading files, and initiating processing. By the end of the process, the submission will be in the "ready for review" status.

The steps to process a typical submission are as follows:

1

Create an empty submission

Call POST /api/submission to create an empty submission.

2

Upload files

Use POST /api/submission/{id}/upload to retrieve a secure file upload URL for each file in your submission. {id} refers to the submission ID from step 1.

The contentType parameter in the request body must be one of the following:

application/pdf
application/msword
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/vnd.ms-excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
image/jpeg
image/heic

PUT the files to the URLs. You will need to do multipart uploading for files exceeding 5MB. Only proceed after all files are finished uploading.

3

Initiate processing

Call POST /api/processing to initate processing. The response payload will include a unique processing event ID, which you can use in step 4:

{
  "eventId": "string",
  "submissionId": "string",
  "message": "The submission has been queued for processing. You may GET the event status using the provided event ID."
}

4

Check processing status

You can check GET /api/processing/{id} to check on the processing event. The response will include a state value:

{
  "id": "string",
  "submissionId": "string",
  "type": "extraction",
  "state": "pending",
  "createdAt": "2025-04-07T12:18:24.000Z",
  "updatedAt": "2025-04-07T12:18:24.000Z"
}

5

Retrieve processed submission

Finally, when the processing event is in the processed state, you can GET /api/submission/{id} to retrieve the full submission to inspect its payload:

{
  "id": "string",
  "submissionNumber": "number",
  "name": "string",
  "template": {
    // Template details
  },
  "templateId": "number",
  "uploaderUserId": "string",
  "userId": "string",
  "files": [
    // List of files
  ],
  "payload": {
    // structed data gathered from files
  }
  "status": "processed",
  "createdAt": "string",
  "updatedAt": "string"
}