Risk Cloud API: Navigating Risk Cloud Data with API v2

Every object in the Risk Cloud API belongs to a five-level hierarchy. Understanding how the levels nest and which IDs are needed at each level is the foundation for most of the API.

This article describes the hierarchy, the parent and child references each response carries, the endpoints for listing children of a parent, and the patterns for paging and incremental sync.

Hierarchy

Application
└── Workflow            (belongs to one Application)
    ├── Step            (belongs to one Workflow)
    │   └── Field       (assigned to a Step scoped to a Workflow or Global)
    └── Record          (an instance of a Workflow; lives on a Step) 
        └── Field value (the Field plus the value captured on this Record)

Application
└── Workflow            (belongs to one Application)
    ├── Step            (belongs to one Workflow)
    │   └── Field       (assigned to a Step scoped to a Workflow or Global)
    └── Record          (an instance of a Workflow; lives on a Step) 
        └── Field value (the Field plus the value captured on this Record)

What each level represents:

• Application. A collection of Workflows, Steps, and logic that together solve a business use case.
• Workflow. A combination of Steps, Paths, Fields, and routing logic that forms a system inside an Application.
• Step. Lives in a Workflow and is configured with Sections, Subsections, and Fields to create a form.
• Field. The template used to capture or display information. A Field has a type (such as SELECT, NUMBER, or DATE) and may define optionValues.
• Record. A form that captures information and moves through the Steps of a Workflow. The Record is the instance of data; its fields array contains the captured values.

Application, Workflow, Step, and Field describe the structure that is built. Records are the data that flows through that structure.

Parent References in Responses

Every response carries pointers to its parents and an object discriminator. This allows the parent chain to be read directly from any object without making additional requests.

• Application has no parent.
• Workflow has an applicationId.
• Step has an embedded workflow reference.
• Field has embedded application and workflow references. Both are null when global is true.
• Record has embedded application, workflow, currentStep, and originStep references.

To walk up the hierarchy, read the parent references on the object that was already fetched. To walk down, use the list endpoints with parent-ID query parameters described in the next section.

Listing Children by Parent ID

Every list endpoint at a child level accepts the parent’s ID as a query parameter.

Workflows in an Application

Returns a paginated list of Workflows. Each entry has an id used in the next step.

Steps in a Workflow

Steps have a type of ORIGIN, CHAIN, or END. Records of a Workflow are created on the ORIGIN Step. Records reaching an END Step are considered complete.

Fields in an Application, Workflow, or Step

The /api/v2/fields endpoint accepts three parent filters.

Two additional query parameters narrow the response:

• field-type: repeatable. Restricts to specific types such as SELECT or DATE.
• scope: one of ALL (default), GLOBAL, or WORKFLOW. Global Fields are not bound to a Workflow. Their application and workflow references are null and global is true.

Records in an Application, Workflow, or Step

The updated-min parameter accepts a Unix epoch timestamp in milliseconds. The response includes only Records modified at or after that time. This is the basis for incremental sync.

Reading a Record’s Parents

A single Record returns its full parent chain inline.

The response includes:

• application: an object with id, name, and object set to "application".
• workflow: an object with id, name, recordPrefix, and object set to "workflow".
• currentStep: an object with id, name, type, and object set to "step".
• originStep: the Step where the Record was created.
• fields: an array of the Record’s captured field values.

No additional calls are required to build a breadcrumb such as “Cyber Risk Management Application / Risk Assessments / Identify Risk.” Every piece is included in the Record response.

Field Definition vs. Field on a Record

Two shapes exist for what looks like a single concept:

A Field definition is what /api/v2/fields returns. It describes the Field’s type, label, helpText, allowed optionValues, and whether it is required. It includes application and workflow parent references.

A Field on a Record appears inside a Record’s fields array. It carries the same id, name, label, and type as the underlying Field definition, plus a values array containing what was captured on this Record.

The captured values are objects with both a textValue and a numericValue. Read them based on the field’s valueType:

• NUMBER. numericValue is the number. textValue is the formatted string (for example, "42").
• OPTION (SELECT, RADIO, MULTI_SELECT, CHECKBOX, E_SIGNATURE). textValue is the option label (for example, "Medium Risk"). numericValue is the option’s numeric weight.
• DATE. numericValue is the Unix epoch in milliseconds. textValue is formatted in the user’s locale.
• USER. textValue is "First Last ([email protected])". numericValue is null.
• TEXT. textValue holds the text. numericValue is null.
• ATTACHMENT. textValue is the filename. numericValue is the version count.
• CALCULATION. numericValue is the computed number. textValue is the labeled result if one is configured.

When reading a value programmatically, branch on valueType first, then choose numericValue or textValue.

Linked Records

Records relate to other Records through Workflow Maps. To traverse those relationships:

The workflow-id parameter is required. It specifies which target Workflow’s Records to return. The depth parameter (default 10) bounds how many relationship hops the response covers. This endpoint is the API equivalent of a Relationship Report.

Pagination

All v2 list endpoints use the same two query parameters:

• page: zero-indexed. Defaults to 0.
• size: defaults to 20. Minimum 1.

The response envelope has three top-level keys:

• content: the array of items.
• page: metadata for the current page, including total pages and total elements.
• links: pre-built URLs for first, prev, next, and last. Following links.next until it is absent is a safe way to iterate without computing page numbers.

Top-Down Traversal

A full top-down sync iterates each level of the hierarchy:

for application in GET /api/v2/applications:
    for workflow in GET /api/v2/workflows?application-id={application.id}:
        for step in GET /api/v2/steps?workflow-id={workflow.id}:
            ...                     # capture form structure
        for field in GET /api/v2/fields?workflow-id={workflow.id}:
            ...                     # capture field definitions
        for record in GET /api/v2/records?workflow-id={workflow.id}:
            ...                     # capture data; record.fields holds captured values

for application in GET /api/v2/applications:
    for workflow in GET /api/v2/workflows?application-id={application.id}:
        for step in GET /api/v2/steps?workflow-id={workflow.id}:
            ...                     # capture form structure
        for field in GET /api/v2/fields?workflow-id={workflow.id}:
            ...                     # capture field definitions
        for record in GET /api/v2/records?workflow-id={workflow.id}:
            ...                     # capture data; record.fields holds captured values

For ongoing sync, change the Records call to include an updated-min parameter set to the latest updated timestamp from the previous run.