Skip to main content
POST
/
api
/
assessments
curl -X POST https://api.example.com/api/assessments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2026 Risk Assessment",
    "companyName": "Acme Coffee Cooperative",
    "companyType": "Cooperative",
    "country": "Kenya",
    "intakeMode": "UPLOAD"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 2026 Risk Assessment",
  "companyName": "Acme Coffee Cooperative",
  "companyType": "Cooperative",
  "country": "Kenya",
  "status": "DRAFT",
  "intakeMode": "UPLOAD",
  "progress": 0,
  "version": 1,
  "overallRiskScore": null,
  "overallRiskLevel": null,
  "userId": "auth0|123456789",
  "createdAt": "2026-03-04T10:30:00.000Z",
  "updatedAt": "2026-03-04T10:30:00.000Z"
}
Create a new risk assessment for a company.

​
Request body

​
name
string
required
Assessment name or identifier.Maximum length: 200 characters.
​
companyName
string
required
Name of the company being assessed.Maximum length: 200 characters.
​
companyType
string
Type or category of company (e.g., “Cooperative”, “Private Company”, “SME”).Maximum length: 100 characters.
​
country
string
Country where the company operates.Defaults to “Kenya” if not provided. Maximum length: 100 characters.
​
intakeMode
string
required
Method for collecting assessment data.Allowed values:
  • UPLOAD - Upload documents for automated analysis
  • GUIDED_INTERVIEW - Step-by-step questionnaire
  • MANUAL_ENTRY - Direct data entry

​
Response

​
id
string
Unique assessment identifier (UUID).
​
name
string
Assessment name.
​
companyName
string
Company name.
​
companyType
string
Company type.
​
country
string
Country of operation.
​
status
string
Current assessment status.Values:
  • DRAFT - Initial state, data collection in progress
  • ANALYZING - AI analysis in progress
  • ACTION_REQUIRED - Waiting for user input or gap resolution
  • COMPLETE - Assessment and report complete
​
intakeMode
string
Data collection method used.
​
progress
number
Completion percentage (0-100).
​
version
number
Version number for optimistic locking.
​
overallRiskScore
number
Aggregated risk score across all categories (0-100). Null until analysis is complete.
​
overallRiskLevel
string
Overall risk classification. Null until analysis is complete.Values: LOW, MODERATE, HIGH, CRITICAL
​
userId
string
ID of the user who created the assessment.
​
createdAt
string
ISO 8601 timestamp of creation.
​
updatedAt
string
ISO 8601 timestamp of last update.
curl -X POST https://api.example.com/api/assessments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2026 Risk Assessment",
    "companyName": "Acme Coffee Cooperative",
    "companyType": "Cooperative",
    "country": "Kenya",
    "intakeMode": "UPLOAD"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 2026 Risk Assessment",
  "companyName": "Acme Coffee Cooperative",
  "companyType": "Cooperative",
  "country": "Kenya",
  "status": "DRAFT",
  "intakeMode": "UPLOAD",
  "progress": 0,
  "version": 1,
  "overallRiskScore": null,
  "overallRiskLevel": null,
  "userId": "auth0|123456789",
  "createdAt": "2026-03-04T10:30:00.000Z",
  "updatedAt": "2026-03-04T10:30:00.000Z"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us