Risk Assessments

Overview

Assessments are the core entity in the CGIAR Risk Intelligence Tool. Each assessment represents a comprehensive risk evaluation for a specific company or partner organization. The platform supports multiple intake modes and tracks assessments through a complete lifecycle from draft to completion.

Assessment Lifecycle

Assessments progress through four distinct statuses:

DRAFT

Initial state when an assessment is created. Users can configure basic details and choose an intake mode.

ANALYZING

Document parsing and AI analysis are in progress. Background jobs are running to extract information.

ACTION_REQUIRED

Gap detection has identified missing or incomplete data fields that need user review and correction.

COMPLETE

Risk analysis is finished. All 7 risk categories have been scored and the final report is available.

Intake Modes

The platform supports three intake modes for gathering assessment data:

Upload

Upload PDF documents (business plans, financial statements) for automated extraction using AWS Textract

Guided Interview

Step-by-step questionnaire that collects information through structured questions

Manual Entry

Direct data entry into structured forms organized by risk category

Creating an Assessment

{
  "name": "Q1 2026 Partnership Assessment",
  "companyName": "Green Valley Agritech",
  "companyType": "Agricultural Cooperative",
  "country": "Kenya",
  "intakeMode": "UPLOAD"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 2026 Partnership Assessment",
  "companyName": "Green Valley Agritech",
  "companyType": "Agricultural Cooperative",
  "country": "Kenya",
  "status": "DRAFT",
  "intakeMode": "UPLOAD",
  "progress": 0,
  "version": 1,
  "overallRiskScore": null,
  "overallRiskLevel": null,
  "userId": "user-123",
  "createdAt": "2026-03-04T10:30:00Z",
  "updatedAt": "2026-03-04T10:30:00Z"
}

Required Fields

Field	Type	Description
`name`	string	Assessment name (max 200 chars)
`companyName`	string	Company being assessed (max 200 chars)
`intakeMode`	enum	One of: `UPLOAD`, `GUIDED_INTERVIEW`, `MANUAL_ENTRY`
`companyType`	string	Optional. Type of organization (max 100 chars)
`country`	string	Optional. Defaults to “Kenya” (max 100 chars)

All assessments are user-scoped. Users can only access assessments they created.

Updating an Assessment

Assessments support optimistic locking to prevent concurrent modification conflicts:

{
  "name": "Q1 2026 Partnership Assessment - Updated",
  "status": "ANALYZING",
  "progress": 25,
  "version": 1  // Current version for conflict detection
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 2026 Partnership Assessment - Updated",
  "status": "ANALYZING",
  "progress": 25,
  "version": 2,  // Version incremented
  ...
}

{
  "statusCode": 409,
  "message": "Assessment was modified by another user. Please refresh and try again.",
  "error": "Conflict"
}

Updatable Fields

name - Assessment name
companyName - Company name
companyType - Company type
status - Assessment status (transitions managed by system in most cases)
progress - Completion percentage (0-100, managed by system)
version - Current version for optimistic locking

The version field is critical for preventing data loss. Always include the current version when updating. The API will return a 409 Conflict if another user has modified the assessment.

Document Upload

For assessments using the UPLOAD intake mode, documents are uploaded via presigned S3 URLs:

Request Upload URL

POST /api/assessments/:id/documents

{
  "fileName": "business-plan.pdf",
  "mimeType": "application/pdf",
  "fileSize": 2048576
}

Response includes a presigned URL and document ID:

{
  "presignedUrl": "https://s3.amazonaws.com/...",
  "documentId": "doc-550e8400"
}

Upload to S3

Upload the file directly to the presigned URL using a PUT request:

await fetch(presignedUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/pdf' },
  body: fileBuffer
});

Trigger Parse

After upload completes, trigger document parsing:

POST /api/assessments/:id/documents/:documentId/parse

{
  "jobId": "job-550e8400"
}

This creates a background job and updates the assessment status to ANALYZING.

Only PDF files are supported. The maximum file size and MIME type validation is enforced at the API level.

Listing Assessments

Retrieve assessments with cursor-based pagination, filtering, and search:

GET /api/assessments?status=COMPLETE&limit=20
GET /api/assessments?search=Green+Valley&cursor=next-cursor-token

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Q1 2026 Partnership Assessment",
      "companyName": "Green Valley Agritech",
      "status": "COMPLETE",
      "progress": 100,
      "overallRiskScore": 42,
      "overallRiskLevel": "MODERATE",
      "createdAt": "2026-03-04T10:30:00Z",
      "updatedAt": "2026-03-04T14:30:00Z"
    }
  ],
  "nextCursor": "cursor-token-for-next-page",
  "total": 156
}

Query Parameters

Parameter	Type	Description
`status`	enum	Filter by: `DRAFT`, `ANALYZING`, `ACTION_REQUIRED`, `COMPLETE`
`search`	string	Search in assessment name or company name (case-insensitive)
`limit`	number	Results per page (default: 10, max: 100)
`cursor`	string	Pagination cursor from previous response

Assessment Statistics

Get aggregated counts by status:

{
  "active": 12,      // ANALYZING status
  "drafts": 8,       // DRAFT status
  "completed": 156,  // COMPLETE status
  "total": 176       // All assessments
}

Comments

Assessments support threaded comments for collaboration:

{
  "content": "Please review the financial risk category - the revenue figures need verification."
}

[
  {
    "id": "comment-123",
    "assessmentId": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user-123",
    "user": {
      "email": "analyst@cgiar.org"
    },
    "content": "Please review the financial risk category...",
    "createdAt": "2026-03-04T11:00:00Z"
  }
]

Deleting an Assessment

Deletion is permanent and cascades to all related data (documents, gap fields, risk scores, recommendations, comments).

DELETE /api/assessments/:id

// Response: 204 No Content

Complete API Reference

POST /api/assessments - Create assessment

Request Body:

{
  name: string;           // Max 200 chars
  companyName: string;    // Max 200 chars
  companyType?: string;   // Max 100 chars
  country?: string;       // Max 100 chars, default: "Kenya"
  intakeMode: 'UPLOAD' | 'GUIDED_INTERVIEW' | 'MANUAL_ENTRY';
}

Response: Assessment object with status DRAFT

GET /api/assessments - List assessments

Query Parameters:

status?: AssessmentStatus
search?: string
limit?: number (default: 10)
cursor?: string

Response: Paginated list with data, nextCursor, total

GET /api/assessments/stats - Get statistics

Response:

{
  active: number;      // Count with status ANALYZING
  drafts: number;      // Count with status DRAFT
  completed: number;   // Count with status COMPLETE
  total: number;       // Total count
}

GET /api/assessments/:id - Get single assessment

Response: Complete Assessment objectErrors:

404 if assessment not found
403 if user doesn’t own the assessment

PUT /api/assessments/:id - Update assessment

Request Body: Partial update with optional version for optimistic lockingResponse: Updated Assessment object with incremented versionErrors:

409 if version conflict detected

DELETE /api/assessments/:id - Delete assessment

Response: 204 No ContentNote: Cascades to all related entities

Code Example: Complete Assessment Creation Flow

import { apiClient } from '@/lib/api-client';

// Step 1: Create assessment
const assessment = await apiClient.post('/api/assessments', {
  name: 'Q1 2026 Partnership Assessment',
  companyName: 'Green Valley Agritech',
  companyType: 'Agricultural Cooperative',
  country: 'Kenya',
  intakeMode: 'UPLOAD'
});

// Step 2: Request upload URL
const { presignedUrl, documentId } = await apiClient.post(
  `/api/assessments/${assessment.id}/documents`,
  {
    fileName: 'business-plan.pdf',
    mimeType: 'application/pdf',
    fileSize: file.size
  }
);

// Step 3: Upload file to S3
await fetch(presignedUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/pdf' },
  body: file
});

// Step 4: Trigger parsing
const { jobId } = await apiClient.post(
  `/api/assessments/${assessment.id}/documents/${documentId}/parse`
);

// Step 5: Poll job status
let job;
do {
  await new Promise(resolve => setTimeout(resolve, 3000));
  job = await apiClient.get(`/api/jobs/${jobId}`);
} while (job.status === 'PENDING' || job.status === 'PROCESSING');

if (job.status === 'COMPLETED') {
  console.log('Document parsed successfully!');
  // Assessment status is now ANALYZING or ACTION_REQUIRED
}

Best Practices

Always Use Version Control

Include the version field when updating assessments to prevent data loss from concurrent edits

Poll Job Status

After triggering document parsing, poll the job status endpoint every 3-5 seconds until completion

Handle 403 Errors

Users can only access their own assessments. Always handle ownership errors gracefully

Validate File Types

Only PDF files are supported for upload. Validate on the client before requesting presigned URLs

Risk Scoring

Learn how assessments are scored across 7 risk categories

AI Analysis

Understand the multi-agent AI pipeline that processes assessments

Report Generation

Generate PDF reports with traffic-light risk indicators

Get Started

Core Features

User Guides

Risk Model

Overview

Assessment Lifecycle

Intake Modes

Upload

Guided Interview

Manual Entry

Creating an Assessment

Required Fields

Updating an Assessment

Updatable Fields

Document Upload

Listing Assessments

Query Parameters

Assessment Statistics

Comments

Deleting an Assessment

Complete API Reference

Code Example: Complete Assessment Creation Flow

Best Practices

Always Use Version Control

Poll Job Status

Handle 403 Errors

Validate File Types

Risk Scoring

AI Analysis

Report Generation

​Overview

​Assessment Lifecycle

​Intake Modes

Upload

Guided Interview

Manual Entry

​Creating an Assessment

​Required Fields

​Updating an Assessment

​Updatable Fields

​Document Upload

​Listing Assessments

​Query Parameters

​Assessment Statistics

​Comments

​Deleting an Assessment

​Complete API Reference

​Code Example: Complete Assessment Creation Flow

​Best Practices

Always Use Version Control

Poll Job Status

Handle 403 Errors

Validate File Types

​Related Resources

Risk Scoring

AI Analysis

Report Generation

Overview

Assessment Lifecycle

Intake Modes

Creating an Assessment

Required Fields

Updating an Assessment

Updatable Fields

Document Upload

Listing Assessments

Query Parameters

Assessment Statistics

Comments

Deleting an Assessment

Complete API Reference

Code Example: Complete Assessment Creation Flow

Best Practices

Related Resources