Risk Management API - Create and Manage Risks

The Risk Management API allows you to integrate risk creation and management capabilities into your existing workflows and systems.

Authentication

All API requests require authentication using your organization's API key:

Authorization: Bearer YOUR_API_KEY

Create Risks

Endpoint

POST /api/risks

Request Body

{
  "risks": [
    {
      "title": "Data Breach Risk",
      "description": "Risk of unauthorized access to customer data",
      "category": "Information Security",
      "likelihood": "Medium",
      "impact": "High", 
      "treatment": "Mitigate",
      "treatmentRationale": "Implement additional security controls",
      "organizationId": "org_123456",
      "ownerUserId": "user_789"
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
risks	Array	Yes	Array of risk objects to create
title	String	Yes	Risk title (max 200 characters)
description	String	Yes	Detailed risk description
category	String	Yes	Risk category classification
likelihood	String	Yes	Risk likelihood (Low, Medium, High, Very High)
impact	String	Yes	Risk impact (Low, Medium, High, Very High)
treatment	String	Yes	Treatment strategy (Accept, Mitigate, Transfer, Avoid)
treatmentRationale	String	No	Explanation for treatment choice
organizationId	String	Yes	Organization identifier
ownerUserId	String	Yes	Risk owner user ID

Response

{
  "message": "Successfully added 1 risks",
  "added": 1,
  "failed": 0,
  "results": [
    {
      "success": true,
      "id": "risk_abc123"
    }
  ]
}

Response Codes

Code	Description
200	Success - Risks created successfully
400	Bad Request - Invalid request body or parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
500	Internal Server Error - Server-side error

Risk Categories

Standard risk categories supported:

• Information Security
• Operational
• Financial
• Compliance & Legal
• Strategic
• Reputational
• Technology
• Human Resources
• Environmental
• Third Party

Likelihood Levels

• Very Low (1)
• Low (2)
• Medium (3)
• High (4)
• Very High (5)

Impact Levels

• Very Low (1)
• Low (2)
• Medium (3)
• High (4)
• Very High (5)

Treatment Strategies

Accept

Accept the risk as-is with no additional controls.

Mitigate

Implement controls to reduce likelihood or impact.

Transfer

Transfer risk to third parties (insurance, contracts).

Avoid

Eliminate the risk by changing processes or activities.

Example Use Cases

Bulk Risk Import

Import risks from existing systems:

const risks = [
  {
    title: "Vendor Service Disruption",
    description: "Critical vendor may fail to deliver services",
    category: "Third Party",
    likelihood: "Medium",
    impact: "High",
    treatment: "Mitigate",
    treatmentRationale: "Establish backup vendor relationships",
    organizationId: "org_123",
    ownerUserId: "user_456"
  },
  {
    title: "Regulatory Change Impact",
    description: "New regulations may require significant compliance changes",
    category: "Compliance & Legal", 
    likelihood: "High",
    impact: "Medium",
    treatment: "Mitigate",
    treatmentRationale: "Monitor regulatory changes and prepare adaptation plan",
    organizationId: "org_123",
    ownerUserId: "user_789"
  }
];

const response = await fetch('/api/risks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({ risks })
});

Integration with Risk Assessment Tools

Automatically create risks from assessment results:

import requests

def create_risk_from_assessment(assessment_result):
    risk_data = {
        "risks": [{
            "title": assessment_result["risk_name"],
            "description": assessment_result["description"],
            "category": map_category(assessment_result["category"]),
            "likelihood": assessment_result["likelihood"],
            "impact": assessment_result["impact"],
            "treatment": "Mitigate",
            "treatmentRationale": "Based on automated assessment",
            "organizationId": "your_org_id",
            "ownerUserId": "assessment_user_id"
        }]
    }
    
    response = requests.post(
        'https://your-domain.com/api/risks',
        json=risk_data,
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    )
    
    return response.json()

Error Handling

Common Errors

Invalid Risk Category

{
  "error": "Invalid risk category",
  "details": "Category must be one of: Information Security, Operational, Financial..."
}

Missing Required Fields

{
  "error": "Missing required fields",
  "details": "title, description, category, likelihood, and impact are required"
}

Organization Access Denied

{
  "error": "Access denied to organization",
  "details": "User does not have permission to create risks for this organization"
}

Rate Limits

• Maximum 100 risks per request
• Maximum 1000 requests per hour per organization
• Bulk operations count as multiple requests based on risk count

SDK Examples

JavaScript/TypeScript

import { FlowGRCClient } from '@flowgrc/sdk';

const client = new FlowGRCClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.flowgrc.com'
});

const newRisk = await client.risks.create({
  title: 'Data Center Outage',
  description: 'Primary data center could experience outage',
  category: 'Technology',
  likelihood: 'Low',
  impact: 'Very High',
  treatment: 'Mitigate',
  organizationId: 'org_123',
  ownerUserId: 'user_456'
});

Python

from flowgrc import FlowGRCClient

client = FlowGRCClient(api_key='your-api-key')

risk = client.risks.create(
    title='Cybersecurity Breach',
    description='Potential unauthorized access to systems',
    category='Information Security',
    likelihood='Medium',
    impact='High',
    treatment='Mitigate',
    organization_id='org_123',
    owner_user_id='user_456'
)

The Risk Management API provides a robust foundation for integrating risk management capabilities into your existing business processes and tools.