Risk Cloud API: Link Records

Updated on: January 02, 2024

Linking records is a powerful offering provided by the Risk Cloud API, enabling users to build out integrations to automate the internal connections of their Risk Cloud data.

Obtain your API Access Token to get started, and for more on record links and workflow maps, refer to our Help Center article Connecting Workflows Together.

Link Records Endpoint

The Records API offers the following Link Records endpoint which allows API users to link records to other records of their respective workflow mappings. Additionally, the endpoint provides the flexibility to either preserve existing linkages or remove them all via the strategy query parameter.

The Link Records endpoint is only available to accounts with Admin level privileges. If you would like to link records via the Risk Cloud API with an API token from a non-Admin account, reference the Link Parent and Child Endpoints section below.

Link Records

POST/api/v1/records/link-by-identifiers

This endpoint has the following query parameter, which can be left empty for the default use case.

Query Parameter Description
strategy Determines the linking strategy of the records:

  • RESPECT_MAPPING (default) - checks to ensure that every record involved has the capacity to be linked
  • REMOVE_EXISTING - removes all relationships between involved records prior to linking

Request Body

Link records by ID

The request body of the Link Records endpoint consists of an array of objects containing recordId properties to set the record IDs of the parent and child records to be linked.

{
  [
    {
      "recordId": "{parent-record-id}"
    },
    {
      "recordId": "{child-record-id}"
    }
  ]
}
Link records by name

The request body of the Link Records endpoint consists of an array of objects containing recordName properties to set the record IDs of the parent and child records to be linked.

{
  [
    {
      "recordName": "{parent-record-name}"
    },
    {
      "recordName": "{child-record-name}"
    }
  ]
}
Link records by primary field

The request body of the Link Records endpoint consists of an array of objects containing primaryFieldValue and workflowId properties to set the record IDs of the parent and child records to be linked.

{
  [
    {
      "primaryFieldValue": "{parent-primary-field-value-string}",
      "workflowId": "{parent-workflow-id}"
    },
    {
      "primaryFieldValue": "{child-primary-field-value-string}",
      "workflowId": "{child-workflow-id}"
    }
  ]
}

Response

The response contains an empty 200 OK if the record linkage was successful.

Link Parent and Child Endpoints

For non-Admin users, linking parent and child records can also be accomplished via the Risk Cloud API with the following endpoints.

POST/api/v1/records/{child-record-id}/parent?layout={layout-id}
POST/api/v1/records/{parent-record-id}/child?layout={layout-id}

Use Case

Get Default Layout

The Link Parent and Child endpoint each require the ID of a layout object. For the purposes of linking records, the default layout is recommended. The ID of the default layout in your Risk Cloud environment can be obtained from the following internal endpoint. The layout ID can be located in the id property of the response.

GET/api/v1/internal/layouts/type/default

Response

{
  "id": "a1b2c3d4",
  "active": true,
  "created": 1512570904482,
  "updated": 1713208740015,
  "title": "Default",
  "defaultLayout": false,
  "workflow": null,
  "layoutType": "Default"
}

Link Parent or Child

Parent or child records reflect the directionality of their corresponding linked workflows. The parent-child relationship of the linked workflows may already be known, however, if it is not known, test each endpoint call with records from each workflow to confirm which one succeeds.

POST/api/v1/records/{child-record-id}/parent?layout={layout-id}
POST/api/v1/records/{parent-record-id}/child?layout={layout-id}

Request

Each of these endpoints take a payload of an ID of the record to link as either a parent or child of the record specified by the child-record-id or parent-record-id in the URL path. Additionally use the layout-id obtained from the steps above.

{
  "id": "a1b2c3d4"
}

Response

200 response and JSON payload confirming the linkage.

Unlink Parent and Child Endpoint

The Records API offers the following Unlink Records endpoint, which allows API users to unlink child records from parent records and vice versa. We currently do not offer bulk unlinking.

DELETE/api/v1/records/{mappedFromRecordId}?map={mappedToRecordId}

 

Request

Required Path Parameter Description
mappedFromRecordId The unique Record Id that belongs to the Workflow, where the Workflow Mapping was first created on.
Query Parameter Description
mappedToRecordId The unique Record Id. This record is linked to the other record as either a child or parent.

Response

200 response.

Use Case Example

  1. I create workflow 1 and workflow 2.
  2. I create the workflow mapping with a relationship of one-to-one on workflow 2.
  3. I create a record w1-1 from workflow 1. I create a record w2-1 from workflow 2.
  4. I link w1-1 to w2-1. I now want to unlink w1-1 from w2-1.
  5. Regardless of which direction I want to unlink it from, I would always have to call api/v1/records/{w2-1_Id}?map={w1-1_Id} because the workflow mapping was originally created on workflow 2.