Skip to main content

​
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:
1

DRAFT

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

ANALYZING

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

ACTION_REQUIRED

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

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"
}

​
Required Fields

FieldTypeDescription
namestringAssessment name (max 200 chars)
companyNamestringCompany being assessed (max 200 chars)
intakeModeenumOne of: UPLOAD, GUIDED_INTERVIEW, MANUAL_ENTRY
companyTypestringOptional. Type of organization (max 100 chars)
countrystringOptional. 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
}

​
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:
1

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"
}
2

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
});
3

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

​
Query Parameters

ParameterTypeDescription
statusenumFilter by: DRAFT, ANALYZING, ACTION_REQUIRED, COMPLETE
searchstringSearch in assessment name or company name (case-insensitive)
limitnumberResults per page (default: 10, max: 100)
cursorstringPagination cursor from previous response

​
Assessment Statistics

Get aggregated counts by status:

​
Comments

Assessments support threaded comments for collaboration: 
{
  "content": "Please review the financial risk category - the revenue figures need verification."
}

​
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

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
Query Parameters:
  • status?: AssessmentStatus
  • search?: string
  • limit?: number (default: 10)
  • cursor?: string
Response: Paginated list with data, nextCursor, total
Response:
{
  active: number;      // Count with status ANALYZING
  drafts: number;      // Count with status DRAFT
  completed: number;   // Count with status COMPLETE
  total: number;       // Total count
}
Response: Complete Assessment objectErrors:
  • 404 if assessment not found
  • 403 if user doesn’t own the assessment
Request Body: Partial update with optional version for optimistic lockingResponse: Updated Assessment object with incremented versionErrors:
  • 409 if version conflict detected
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

​
Related Resources

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