Risk Cloud API: Bulk Link Records

Updated on: September 05, 2024

Please reference our Bulk Link Records Help Article for in-depth information about the functionality and permissions needed. 

Obtain your API Access Token to get started.

Table of Contents

Step 1 Setup Bulk Link Record Request

Step 2 Upload and Verify File on Bulk Link Record Request

Step 3 Process File and Complete Record Linking

Step 4 Other

Step 1 Setup Bulk Link Records Request

1.1 Check for Incomplete Bulk Link Record Request

This endpoint will verify if you have any incomplete Bulk Link Record (BLR) Request. Ideally, we should only run ONE unique set of workflow (wf) /step combination at a time. The order matters, so the reverse is possible as long as we don't have the exact same workflow/step combination. The combination will be available once the the latest one completes or fails.

Possible combinations Ex.

Input New BLR Request (req) Existing BLR Request [STATUS] Allowed?
req#1 wf1 / step 1 -> wf1 / step 2 none yes - no other active request exist
req#2 wf1 / step 1 -> wf1 / step 2 req#1 wf1 / step 1 -> wf1 / step 2

[PROCESSING / PENDING UPLOAD / FILE ERRORS /  SYSTEM ERROR]

 no - one other active request exist
req#2 wf1 / step 1 -> wf1 / step 2 req#1  wf1 / step 1 -> wf1 / step 2

[COMPLETED / COMPLETED WITH ERROR]

 yes - no other active request exist
req#2 wf1 / step 1 -> wf1 / step 2 req#1 wf1 / step 2 -> wf1 / step 1

[PROCESSING / PENDING UPLOAD / FILE ERRORS /  SYSTEM ERROR]

 yes - reverse case is still acceptable
req#2 wf1 / step 1 -> wf1 / step 2 req#1 wf1 / step 2 -> wf1 / step 1

[COMPLETED / COMPLETED WITH ERROR]

 yes - reverse case is still acceptable
GET/api/v1/bulk-link-records/hasRequestInProgress

This endpoint has the following parameters:

Query Parameter Required Description 
sourceWorkflowId
 No The first workflow Id you selected. 
targetWorkflowId

 

 No The second workflow Id you selected.

 

Response

Response Parameter Description
boolean Return true if it has an incomplete request.

Return false if it does NOT have an incomplete request.

1.2 Create Bulk Link Records Endpoint

This endpoint will create a new Bulk Link Record Request. We recommend you verify that there are no incomplete Bulk Link Record Request before proceeding with this endpoint.

POST/api/v1/bulk-link-records/source/{sourceWorkflowId}/target/{targetWorkflowId}

This endpoint has the following parameters:

Required Path Parameter Description
sourceWorkflowId The first workflow id you selected.
targetWorkflowId The second workflow id you selected.

 

Response

<BulkLinkRecordsResult>

Response Parameter Description
id The Bulk Link Record Request Id.
creator The Bulk Link Record Request creator.
submitter The Bulk Link Record Request submitter.
dateCompleted The date the Bulk Link Record Request was completed.
dateCreated The date the Bulk Link Record Request was created.
status The current status for the Bulk Link Record Request.
sourceWorkflowId The first workflow Id.
sourceWorkflowName The first workflow name.
sourceApplicationId The first workflow > application Id.
sourceApplicationName The first workflow > application name.
sourceApplicationIcon The first workflow > application icon.
sourceApplicationColor The first workflow > application color.
targetWorkflowId The second workflow Id.
targetWorkflowName The second workflow name.
targetApplicationId The second workflow > application Id.
targetApplicationName The second workflow > application name.
targetApplicationIcon The second workflow > application icon.
targetApplicationColor The second workflow > application color.
workflowMapType The workflow relationship mapping type between the first and second workflow.
fileName The name of the file you uploaded.
errorTemplateCount The number of errors found on your uploaded file.
requestTotal The total number of rows you aimed to link after your Bulk Link Record Request finished processing.
requestSuccessTotal The total number of successful links after your Bulk Link Record Request finished processing.
requestErrorTotal The total number of unsuccessful links after your Bulk Link Record Request finished processing.

Step 2 Upload and Verify File on Bulk Link Record Request

2.1 Download Bulk Link Record Template

This endpoint will download the bulk link record template file for your Bulk Link Record Request. You populate it with data and upload it later.

GET/api/v1/bulk-link-records/template/{requestId}

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.

 

Response

Response Parameter Description
ModelAndView Returns the base template xlsx file.

2.2 Upload File

This endpoint will upload your file to the given Bulk Link Record Request. It will perform a high level validation check and should pass before processing. It does not do any detailed level validation or actual record linking.

POST/api/v1/bulk-link-records/import/{requestId}

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.
file The file you want to upload to process. Can be in xlsx or csv format.

 

Response

<BulkLinkRecordsResult> - same as 1.2 Response.

2.3 Delete File

This endpoint will delete the file from the given Bulk Link Record Request. You can run the upload file endpoint again to add a new file.

DELETE/api/v1/bulk-link-records/{requestId}/file

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.

 

Response

<BulkLinkRecordsResult> - same as 1.2 Response.

 

Step 3 Process File and Complete Record Linking

3.1 Process File

This endpoint will start the file process. We recommend the file passing the high level validation check before proceeding. This endpoint will perform a detailed level validation check and either result in (1) failed detailed level validation > download file validation error summary, no records were linked (2) passed detailed level validation > download completed / completed with error summary, records were linked.

POST/api/v1/bulk-link-records/process/{requestId}

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.

 

Response

200 status code with an empty body.

 

3.2 Route 1 Failed Detailed Level Validation > Download File Validation Error Summary

This endpoint will download the validation error summary. The file failed the detailed level validation check. The Bulk Link Record Request should have the status FILE_ERRORS. No records have been linked.

GET/api/v1/bulk-link-records/error-template/{requestId}

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.

 

Response

Response Parameter Description
ModelAndView Returns the validation error summary in xlsx format.

 

3.3 Route 2 Passed Detailed Level Validation > Download Processed Completed (with Errors) Summary

This endpoint will download the completed (with errors) summary. The file passed the detailed level validation check. The Bulk Link Record Request should have the status COMPLETED or COMPLETED_WITH_ERRORS. Records should have been linked.

GET/api/v1/bulk-link-records/summary/{requestId}

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.

 

Response

Response Parameter Description
ModelAndView Returns the completed / completed with errors summary in xlsx format.

 

Step 4 Other

4.1 Find Bulk Link Record Request

This endpoint will find the given Bulk Link Records Request.

GET/api/v1/bulk-link-records/{requestId}

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.

 

Response

<BulkLinkRecordsResult> - same as 1.2 Response.

 

4.2 Find All Bulk Link Record Request

This endpoint will find all the Bulk Link Records Request that you have access to.

GET/api/v1/bulk-link-records/all

This endpoint has the following parameters:

Query Parameter Required Description 
pageable params

 

 No Optional pageable fields ex sort or size.

 

Response

Response Parameter Description
Page<BulkLinkRecordsResult> Pageable list of BulkLinkRecordsResult.

<BulkLinkRecordsResult> - same as 1.2 Response.

 

4.3 Deactivate Bulk Link Record Request

This endpoint will deactivate the given Bulk Link Records Request.

DELETE/api/v1/bulk-link-records/{requestId}/deactivate

This endpoint has the following parameters:

Required Path Parameter Description
requestId The unique Bulk Link Records Request Id.

Response

<BulkLinkRecordsResult> - same as 1.2 Response.