Risk Cloud API: Bulk Import Records

Updated on: July 31, 2024

Records can be imported in bulk from CSV and XLSX import files in the Risk Cloud web application.  This functionality can also be leveraged via the Risk Cloud API's Bulk Import API endpoints.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Bulk Import Records Endpoint

The internal Record API offers the following Bulk Import Records endpoint, allowing custom integrations to create records on a given step based on data provided in a CSV or XLSX file payload, structured based off of the given Risk Cloud layout.

The endpoint is available to all users with the Import entitlement.

POST/api/v1/internal/records/import?step={step-id}&layout={layout-id}

This endpoint has the following query parameters.

Property Requiredness Description
step required The unique ID of the step to create a records on.
layout required The unique ID of the Risk Cloud layout that defines the column headers and structure in the attached CSV or XLSX payload.

Request

The CSV or XLSX file should have headers reflecting the field names of the fields in the specified Risk Cloud layout. For example, if the layout contains custom fields "Name", "Description", and "Amount", a valid and importable CSV would be formatted as shown below.

Title,Description,Amount
Phishing,Deceptive attempts to obtain sensitive information by masquerading as a trustworthy entity,9
Malware,Malicious software designed to compromise a device or network.,8
DDoS Attacks,Overwhelming a network or service with excessive traffic to cause disruption.,7

The CSV or XLSX file can be sent in the request using the  multipart/form-data content type with a key named file and a value of the import CSV or XLSX file (often represented by HTTP request libraries or tools as the path to the file).

A cURL sample is demonstrated below:

curl --location 'https://your-company.logicgate.com/api/v1/internal/records/import?step={step-id}&layout={layout-id}' \\
--header 'Authorization: Bearer {API_TOKEN}' \\
--form 'file=@"/the/path/to/file/import.csv"'

Response

{
  "importType": "ImportRecordRequest",
  "id": "{{import-record-request-id}}",
  "layoutSnapshot": null,
  "batchRecordImport": null
}
Notable Property Description
id The unique ID of the bulk import record request, which can be used to keep track of the bulk import status.

Bulk Import Status Endpoint

Once the Bulk Import Records endpoint receives a successful request, it begins asynchronously importing the records in the given CSV or XLSX file.

To keep track of the import status, the following Bulk Import Status endpoint can be polled periodically until it returns a payload containing the statusproperty as COMPLETED.

POST/api/v1/internal/records/import/{id}
Path Property Description
id The unique ID of the bulk import record request, which can be used to keep track of the bulk import status.

Response

{
  "importRequestId": "{{import-request-id}}",
  "completed": 1722459144960,
  "totalRows": 2,
  "invalidRows": 0,
  "validRows": 2,
  "status": "COMPLETED",
  "creator": {
    "id": "{{user-id}}",
    "email": "[email protected]",
    ....
  }
  ...
}
Notable Property Description
importRequestId The unique ID of the bulk import record request, which can be used to keep track of the bulk import status.
completed A unix timestamp in milliseconds of the completion time of the bulk import operation.
totalRows The total number of rows to be imported
invalidRows The number of rows that were marked as invalid in the import
validRows The number of rows that were marked as valid in the import
status The status of the bulk import operation, once the value is COMPLETED the bulk import operation is complete.

Resources

Get Layout ID

The layout represents the field columns of the CSV or XLSX export. The layout-id can be obtained from the Risk Cloud web application or via the Risk Cloud API. Additionally, custom layouts may be created for specific integration use cases.

Using the Risk Cloud application

The most straightforward way to find a layout ID is to open the desired layout from the builder page located at Build > Layouts in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/build/layouts/{layout-id}

Using the Risk Cloud API

The Retrieve Layouts endpoint returns all layouts that the user is entitled to, either as an Admin, Builder, or Step Permission Set grantee. If no layouts are returned, check the permissions of the requesting API user to ensure that proper permissions are granted.

GET/api/v1/layouts

This will return an array of layout objects, each looking like the following. Parse the layout objects by properties like workflow, application, or title until you have located the intended layout.

{
  "id": "a1b2c3d4",
  "title": "[Reg Compliance] Assessments",
  "defaultLayout": true,
  "workflow": {
    "id": "e5f6g7h8",
    "name": "Risk and Impact Assessments",
    "application": {
      "id": "i8j9k0l1",
      "name": "RCX: Regulatory Compliance",
      ...
    },
    ...
  },
  "layoutType": "Display",
  ...
}

Get Step ID

The step ID for the stepId property can be obtained from either your Risk Cloud web app environment directly or from the Risk Cloud API.

Get Step ID (Web App Environment)

The step ID can be located within your Risk Cloud web app environment in the following location:

  • Navigate to Build > Applications
  • Search for and open the application containing the step
  • Open the workflow containing the step
  • Open the step
  • The step ID can be found in the web browser URL bar https://environment.logicgate.com/build/steps/{step-id}

Get Step ID (Risk Cloud API)

The step ID can be located via the Retrieve Steps endpoint, specifically in the id property of step objects returned in the content property of the response.

GET/api/v2/steps