Skip to main content
In Heron, files are grouped together into submissions (also called end users). A submission represents data relating to an entity in your workflow, such as an applicant business, plaintiff, etc. This guide will walk you using the Heron API to:
  • Create a new submission,
  • Upload files or raw data to that submission,
  • Start the Heron workflow processing for that submission, and
  • Retrieve the parsed data from files in the submission.

​
Create a New Submission

Creating a new submission requires sending a POST request to the /end_users endpoint. The request body should include the end_user_id of the submission which should be a unique reference to the submission in your system. You may also include a name field to give the submission a human-readable name. 
const BASE_URL = 'https://app.herondata.io/api';
const API_KEY = 'key_xxxxxxxxx';

const response = await fetch('/api/end_users', {
	method: 'POST',
	headers: {
		"x-api-key": `${API_KEY}`,
	},
	body: JSON.stringify({
		end_user: {
			end_user_id: '[END_USER_ID]',
			name: 'New Submission',
		},
	}),
});

if (!response.ok) {
	throw new Error(`Failed to create submission: ${response.statusText}`);
}

const response_body = await response.json();
//    ^ { end_user: { heron_id: 'eus_12345342', name: 'New Submission', end_user_id: '[END_USER_ID]' } }

const end_user_heron_id = response_body.end_user.heron_id;

​
Upload Files to a Submission

Now we’ve created a new submission to hold our files, we can upload files to it and start extracting data from them. To upload a file to a submission, send a POST request to the /end_users/{heron_id}/files/v2 endpoint as a multipart/form-data request with the file attached. The file_class may be omitted, in which case Heron will classify the file based on its contents. 
const formData = new FormData();
formData.append('file', fileBlob, 'file.pdf');
formData.append('file_class', 'bank_statement');
formData.append('reference_id', 'file_1234');

const response = await fetch(`${BASE_URL}/end_users/${end_user_heron_id}/files/v2`, {
	method: 'POST',
	headers: {
		"x-api-key": `${API_KEY}`,
	},
	body: formData,
});

const response_body = await response.json();

const file_heron_id = response_body.heron_id;

​
Starting Heron Workflow Processing

Once all files for a given submission have been uploaded, you can start the Heron workflow processing by sending a POST request to the /end_users/{heron_id}/start_workflow endpoint. This will trigger Heron to start processing the files in the submission and extracting data from them.

​
Retrieve Parsed Data from Uploaded Files

Now we’ve uploaded a file, we can poll the /end_users/{end_user_id_or_heron_id}/files endpoint to retrieve the parsed data from files in the submission. The response body will be an array of files in the submission, and will contain a parsed_results array for each file. This array will contain the extracted data from the file and and a parsing_status field indicating the status of the parsing process, you should continue to poll this endpoint until the parsing status is either succeeded or failed. 
const response = await fetch(`/api/end_users/${end_user_heron_id}/files`, {
	headers: {
		"x-api-key": `${API_KEY}`,
	},
});

const response_body = await response.json();
// ^ [{ heron_id: "euf_xxxxx", parsed_results: [ { ... } ] }]
We can also subscribe to webhooks to be notified when the parsing process is complete, this can be configured via the Heron Dashboard. Please reach out to support for further details on setting up or configuring webhooks.