Sharing request redirect flow

Use the Sharing Request redirect flow to send your applicant to Akahu Apply for data collection, and have them returned to your product on completion.

1. Create Application

Use the POST /v1/applications endpoint to create a new Application for data Resources to be collected into.

When creating an Application, the reference field must be included. This provides a way to identify the Application in Akahu Apply using a reference from your system.

You should create a new Application for each logical data boundary in your system. For lending use cases, an Application should be created for each assessment you wish to perform. In the case of joint applicants, where you wish to analyse the data relating to many applicants as a single unit, a single Application should be shared by all applicants.

2. Create Sharing Request

Use the POST /v1/applications/{applicationId}/sharing-request endpoint to create a sharing request for your user.

When creating a sharing request, specify a value of requested_days between 30 and 365. This determines how much historical data (i.e. bank statements) will be requested of the user.

To use the redirect flow, the redirect_uri must also be provided at the time of creating the Sharing Request. This should reference a location in your application that the user will be returned to on completion of the Sharing Request.

3. Navigate the user to Akahu Apply

The newly created Sharing Request will have a field named link, which contains a unique Akahu Apply URL for that Sharing Request.

Navigate your user in their web browser to this link to begin the Sharing Request.

4. Handle result redirect

Upon exiting the Akahu Apply Sharing Request flow, your user will be returned to the redirect_uri that you provided when creating the Sharing Request.

Details about the outcome are provided as query parameters in the URL:

The action parameter provides the overall result of the Sharing Request:

cancelled means that the user exited the Sharing Request without submitting any data.
submitted means that the user exited the Sharing Request after successfully submitting some data.

The applicationId parameter includes the ID of the Application that the Sharing Request relates to.

The sharingRequestId parameter includes the ID of the specific Sharing Request.

5. Wait for processing to complete

Poll the GET /v1/applications/{applicationId}/resources endpoint until all available resources are assigned a terminal status of completed or failed. This ensures that Akahu Apply has completed all processing prior to generating a Report.

6. Generate a Report

Use the POST /v1/applications/{applicationId}/reports endpoint to generate a Report.

Use the returned Report _id to poll the GET /v1/applications/{applicationId}/reports/{reportId} endpoint, until the Report is assigned a terminal status of completed or failed. If the Report processing fails, more information about the error will be available in the failure_reason attribute of the Report.

7. Access Report data

Access the compiled report dataset using the following endpoints:

8. Archive the Application

Once you’ve accessed the data you need, be sure to archive the Application using the PUT /v1/applications/{applicationId}/archive endpoint.

Archived applications will be retained for your org’s retention period (default 90 days) before being permanently deleted.

You can continue to access an Application while it is archived. However, an archived application is effectively immutable and cannot have more data Resources added.

An application can be restored from archive during the retention period if you change your mind.

Direct upload

Use the direct upload flow to process files that you've already collected from applicants.

1. Create Application

Use the POST /v1/applications endpoint to create a new Application for data Resources to be collected into.

When creating an Application, the reference field must be included. This provides a way to identify the Application in Akahu Apply using a reference from your system.

2. Upload existing files

a. Create a Document

For each file you wish to upload, use the POST /v1/applications/{applicationId}/documents endpoint to create a new Document.
When creating the document you must include the name field. This is used to refer to the document from within the report, so the more descriptive the better. It should include the file extension (.pdf).

The endpoint will create the record in Akahu Apply, and return an ID and a unique upload_url - take note of this for the next step.

ℹ️
Any Document records created via this endpoint that do not have a file uploaded within a short time will be deleted. Ensure that any uploads are completed before the expires_at timestamp returned from this endpoint.

b. Upload the file

Make a PUT request to the upload_url you created previously, sending your file in the request body.

The following restrictions apply when uploading:

The file must be no larger than 50MB.
The Content-Type header must be application/pdf.
The upload URL must not have expired.
The upload URL may only be used once.

3. Wait for processing to complete

Poll the GET /v1/applications/{applicationId}/resources endpoint until the uploaded Documents are assigned a terminal status of completed or failed. This ensures that Akahu Apply has completed all processing prior to generating a Report.

If a Document fails during processing, more information about the error will be available in the failure_reason attribute of the Document.
These failures are generally related to the PDF file itself, for example an encrypted PDF file will end up with a failed status.

4. Check Document contents

While a PDF file may have been processed successfully, Akahu Apply may or may not have extracted financial statements from it.
To ensure that the Documents have the correct number of financial statements present, you can use the content_details field.

The content_details field provides a summary of which pages have been processed, skipped, or unprocessed.

If a range of pages was processed, a financial statement was found and successfully extracted from those pages.

If a range of pages was skipped, Akahu Apply did not process those pages. This predominantly happens in the case of blank pages.

If a range of pages was unprocessed, either the content is not supported by Akahu Apply, or an error occurred while attempting to extract data from these pages.

5. Generate a Report

Use the POST /v1/applications/{applicationId}/reports endpoint to generate a Report.

6. Access Report data

Access the compiled report dataset using the following endpoints:

7. Archive the Application

Once you’ve accessed the data you need, be sure to archive the Application using the PUT /v1/applications/{applicationId}/archive endpoint.

Archived applications will be retained for your org’s retention period (default 90 days) before being permanently deleted.

You can continue to access an Application while it is archived. However, an archived application is effectively immutable and cannot have more data Resources added.

An application can be restored from archive during the retention period if you change your mind.