Quickstart

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,
• 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 ENCODED_API_KEY = btoa(`:${API_KEY}`);

const response = await fetch('/api/end_users', {
	method: 'POST',
	headers: {
		Authorization: `Basic ${ENCODED_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 endpoint, providing a base64-encoded file, the file class, and the filename. The file class may be omitted, in which case Heron will classify the file based on its contents.

const response = await fetch(`/api/end_users/${end_user_heron_id}/files`, {
	method: 'POST',
	headers: {
		Authorization: `Basic ${ENCODED_API_KEY}`,
	},
	body: JSON.stringify({
		file_base64: '[BASE64_ENCODED_FILE]',
		file_class: 'bank_statement',
		filename: 'file.pdf',
		reference_id: 'file_1234',
	}),
});

const response_body = await response.json();

const file_heron_id = response_body.heron_id;

​

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: {
		Authorization: `Basic ${ENCODED_API_KEY}`,
	},
});

const response_body = await response.json();
// ^ [{ heron_id: "euf_xxxxx", parsed_results: [ { ... } ] }]