Underwriting Rail

Underwriting Rail

Risk underwriting, proposal evaluation, and approval workflows.

Overview

The Underwriting Rail provides endpoints for evaluating risk proposals, managing underwriting workflows, and automated decision-making.

Base URL

/api/v1/underwriting

Endpoints

Create Proposal

POST /api/v1/underwriting/proposals

Submit a new underwriting proposal.

Request Body:

{
  "type": "TAKAFUL",
  "applicantId": "cust_123",
  "productCode": "TAK_LIFE_001",
  "coverageAmount": "1000000.00",
  "currency": "SAR",
  "term": 20,
  "applicantData": {
    "age": 35,
    "occupation": "PROFESSIONAL",
    "smoker": false,
    "healthDeclarations": []
  }
}

Response:

{
  "data": {
    "proposalId": "prop_abc123",
    "status": "PENDING_EVALUATION",
    "submittedAt": "2025-01-15T10:00:00Z",
    "estimatedDecision": "2025-01-16T10:00:00Z"
  }
}

Evaluate Proposal

POST /api/v1/underwriting/proposals/:proposalId/evaluate

Trigger automated evaluation.

Response:

{
  "data": {
    "proposalId": "prop_abc123",
    "decision": "APPROVED",
    "riskClass": "STANDARD",
    "premium": "5000.00",
    "premiumFrequency": "ANNUAL",
    "loadings": [],
    "exclusions": [],
    "conditions": ["Medical exam required for coverage > 2M"],
    "validUntil": "2025-02-15"
  }
}

Get Proposal

GET /api/v1/underwriting/proposals/:proposalId

Retrieve proposal details.

List Proposals

GET /api/v1/underwriting/proposals

Query Parameters:

Parameter	Type	Description
status	string	Filter by status
type	string	Filter by proposal type
assignedTo	string	Filter by underwriter

Manual Review

POST /api/v1/underwriting/proposals/:proposalId/review

Submit manual review decision.

Request Body:

{
  "decision": "APPROVED_WITH_CONDITIONS",
  "riskClass": "SUBSTANDARD",
  "loadings": [
    {
      "type": "OCCUPATIONAL",
      "percent": 25,
      "reason": "High-risk occupation"
    }
  ],
  "exclusions": ["Aviation activities"],
  "notes": "Manual review due to occupation"
}

Calculate Premium

POST /api/v1/underwriting/premium/calculate

Calculate premium for a proposal.

Request Body:

{
  "productCode": "TAK_LIFE_001",
  "coverageAmount": "1000000.00",
  "term": 20,
  "riskClass": "STANDARD",
  "loadings": []
}

Get Risk Classes

GET /api/v1/underwriting/risk-classes

Get available risk classes and criteria.

Proposal Types

Type	Description
TAKAFUL	Takaful insurance
FINANCING	Financing facility
INVESTMENT	Investment product
TRADE	Trade finance

Decision Types

Decision	Description
APPROVED	Automatically approved
APPROVED_WITH_CONDITIONS	Approved with conditions
REFER	Referred for manual review
DECLINED	Application declined
PENDING_INFO	Additional info needed

Risk Classes

Class	Description
PREFERRED	Better than standard risk
STANDARD	Normal risk
SUBSTANDARD	Higher than standard risk
DECLINED	Unacceptable risk

Events

Event	Description
underwriting.proposal.submitted	Proposal submitted
underwriting.proposal.evaluated	Evaluation completed
underwriting.proposal.approved	Proposal approved
underwriting.proposal.declined	Proposal declined
underwriting.proposal.referred	Referred for review

See Also

• Risk Rail - Risk assessment
• Contracts Rail - Contract creation