Governance Rail

Governance Rail

Shariah board management, fatwa tracking, and governance workflows.

Overview

The Governance Rail provides endpoints for managing Shariah governance structures, board decisions, fatwa tracking, and compliance with Islamic finance standards.

Base URL

/api/v1/governance

Endpoints

Create Board

POST /api/v1/governance/boards

Create a Shariah supervisory board.

Request Body:

{
  "name": "Shariah Supervisory Board",
  "type": "SHARIAH",
  "jurisdiction": "SAU_SAMA",
  "members": [
    {
      "name": "Dr. Ahmad Abdullah",
      "role": "CHAIRMAN",
      "qualifications": ["PhD Islamic Finance", "AAOIFI Certified"],
      "startDate": "2025-01-01"
    }
  ],
  "quorum": 3,
  "votingRules": "MAJORITY"
}

Response:

{
  "data": {
    "boardId": "board_abc123",
    "name": "Shariah Supervisory Board",
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Create Resolution

POST /api/v1/governance/resolutions

Create a board resolution.

Request Body:

{
  "boardId": "board_abc123",
  "type": "PRODUCT_APPROVAL",
  "subject": "New Murabaha Product Structure",
  "description": "Review and approval of new vehicle financing product",
  "documents": ["doc_xyz"],
  "requiredVotes": 3
}

Record Vote

POST /api/v1/governance/resolutions/:resolutionId/votes

Record a board member vote.

Request Body:

{
  "memberId": "member_123",
  "vote": "APPROVE",
  "conditions": ["Annual Shariah audit required"],
  "notes": "Structure compliant with AAOIFI Standard 8"
}

Issue Fatwa

POST /api/v1/governance/fatwas

Issue a Shariah ruling (fatwa).

Request Body:

{
  "boardId": "board_abc123",
  "resolutionId": "res_xyz",
  "type": "PRODUCT",
  "subject": "Vehicle Murabaha Financing",
  "ruling": "PERMISSIBLE",
  "conditions": [
    "Asset must be halal",
    "Markup disclosed upfront",
    "No penalties on early payment"
  ],
  "references": ["AAOIFI Standard 8", "Quran 2:275"],
  "effectiveDate": "2025-02-01"
}

Get Fatwa

GET /api/v1/governance/fatwas/:fatwaId

Retrieve fatwa details.

List Fatwas

GET /api/v1/governance/fatwas

Query Parameters:

Parameter	Type	Description
type	string	PRODUCT, TRANSACTION, GENERAL
ruling	string	PERMISSIBLE, PROHIBITED, CONDITIONAL
status	string	ACTIVE, SUPERSEDED, REVOKED

Schedule Meeting

POST /api/v1/governance/meetings

Schedule a board meeting.

Request Body:

{
  "boardId": "board_abc123",
  "type": "REGULAR",
  "scheduledDate": "2025-02-01T10:00:00Z",
  "agenda": ["Product approvals", "Compliance review", "New fatwa requests"],
  "attendees": ["member_1", "member_2", "member_3"]
}

Get Compliance Report

GET /api/v1/governance/compliance/report

Get Shariah compliance report.

Query Parameters:

Parameter	Type	Description
period	string	MONTHLY, QUARTERLY, ANNUAL
year	number	Report year

Board Types

Type	Description
SHARIAH	Shariah Supervisory Board
AUDIT	Shariah Audit Committee
INVESTMENT	Investment Committee
RISK	Risk Committee

Resolution Types

Type	Description
PRODUCT_APPROVAL	New product approval
POLICY_CHANGE	Policy modification
EXCEPTION	Exception approval
GENERAL	General ruling

Fatwa Rulings

Ruling	Description
PERMISSIBLE	Halal - allowed
PROHIBITED	Haram - forbidden
CONDITIONAL	Allowed with conditions
MAKRUH	Discouraged but not forbidden

Events

Event	Description
governance.resolution.created	Resolution created
governance.resolution.approved	Resolution approved
governance.fatwa.issued	Fatwa issued
governance.meeting.scheduled	Meeting scheduled

See Also

• Compliance Rail - Compliance checks
• Contracts Rail - Contract management