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 - coming soon!

Using the direct upload feature, you will be able to upload Documents to an Application directly via API. This feature can be used to process files that you've already collected from your applicants using other methods.

We're currently working on this feature, and expect to have it available for API customers in early August.