Skip to main content

​
Overview

Organization Settings control core configuration for your organization, including name, accounting period, notification preferences, and advanced loan/dividend rules.
Permission required:
  • settings:read (to view settings)
  • settings:write (to modify settings)
Some settings like currency and timezone are immutable after organization creation to ensure data integrity.

​
API Endpoints

​
Get Organization Settings

Retrieve organization configuration: 
GET /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}
Response: 
{
  "message": "Organization details retrieved successfully",
  "data": {
    "id": "org-abc123",
    "numericId": 42,
    "name": "Agatabo Cooperative ABC",
    "type": "TONTINE",
    "currencyCode": "RWF",
    "amountScale": 0,
    "accountingPeriod": "MONTHLY",
    "enableEmail": true,
    "enableSms": false,
    "directionalRounding": false,
    "timezone": "Africa/Kigali",
    "dateFormat": "DD/MM/YYYY",
    "loanSettings": { ... },
    "dividendSettings": { ... },
    "onboardingCompleted": true,
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

​
Update Organization Name

Update organization display name: 
PUT /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}
Body:
{
  "name": "New Organization Name"
}
Response: 
{
  "message": "Organization updated successfully",
  "data": {
    "id": "org-abc123",
    "name": "New Organization Name",
    ...
  }
}

​
Update Organization Settings

Update operational settings: 
PUT /organizations/{id}/settings
Headers:
  x-organization-id: {organizationId}
Body:
{
  "accountingPeriod": "MONTHLY",
  "enableEmail": true,
  "enableSms": false,
  "loanSettings": { ... },
  "dividendSettings": { ... }
}
Request body fields:
FieldTypeRequiredDescription
accountingPeriodenumNoPeriod type: MONTHLY, QUARTERLY, YEARLY
enableEmailbooleanNoEnable email notifications
enableSmsbooleanNoEnable SMS notifications
loanSettingsobjectNoLoan policies and rules
dividendSettingsobjectNoDividend distribution settings
Response: 
{
  "message": "Organization settings updated successfully"
}
Important: accountingPeriod cannot be changed after periods have been closed.

​
Configurable Settings

​
Organization Name

Field: name Description: Display name shown throughout application Example: “Agatabo Cooperative ABC” API: PUT /organizations/{organizationId} 
{
  "name": "New Organization Name"
}
Usage: Appears on reports, dashboards, and member communications

​
Accounting Period

Field: accountingPeriod Values: MONTHLY, QUARTERLY, YEARLY Default: MONTHLY API: PUT /organizations/{id}/settings 
{
  "accountingPeriod": "MONTHLY"
}
Frequency:
  • MONTHLY: Close books every month (recommended)
  • QUARTERLY: Close books every 3 months
  • YEARLY: Close books annually
Validation: Cannot change after periods have been closed. Error if periods closed: 
{
  "message": "Cannot change accounting period after closing periods. Please contact support."
}
Recommendation: Use MONTHLY for active organizations. Use QUARTERLY or YEARLY only for low-activity organizations. See: Period Closing

​
Email Notifications

Field: enableEmail Type: boolean Default: true API: PUT /organizations/{id}/settings 
{
  "enableEmail": true
}
When enabled, sends email notifications for:
  • Loan approvals
  • Loan payment reminders
  • Loan payment confirmations
  • Contribution reminders
  • General announcements
Requirements:
  • Members must have email addresses in profiles
  • Email service must be configured by system administrator

​
SMS Notifications

Field: enableSms Type: boolean Default: false API: PUT /organizations/{id}/settings 
{
  "enableSms": true
}
When enabled, sends SMS notifications for:
  • Loan approvals
  • Loan payment reminders
  • Urgent notifications
Requirements:
  • Members must have phone numbers in profiles
  • Pindo SMS service must be configured by administrator
  • SMS credits must be available
Cost: SMS messages incur per-message charges

​
Loan Settings

Field: loanSettings Type: JSON object API: PUT /organizations/{id}/settings Example configuration: 
{
  "loanSettings": {
    "min_loan_amount": 50000,
    "max_loan_amount": 5000000,
    "interest_rate": 10,
    "coverage_ratio": 1.2,
    "min_savings_ratio": 0.3,
    "max_loan_percentage": 3.0,
    "disbursement_fee_percentage": 1.0
  }
}
Available fields:
FieldTypeDescription
min_loan_amountnumberMinimum loan amount allowed
max_loan_amountnumberMaximum loan amount allowed
interest_ratenumberDefault interest rate (percentage)
coverage_rationumberLoan-to-collateral ratio
min_savings_rationumberMinimum savings as % of loan
max_loan_percentagenumberMax loan as multiple of savings
disbursement_fee_percentagenumberFee charged on disbursement (%)
Important:
  • Percentage fields stored as decimals in database (10% = 0.1)
  • API accepts percentages, converts automatically
  • Invalid settings can prevent loan creation
  • Modify with technical assistance

​
Dividend Settings

Field: dividendSettings Type: JSON object API: PUT /organizations/{id}/settings Example configuration: 
{
  "dividendSettings": {
    "default_distribution_method": "by_contribution",
    "min_pool_amount": 100000,
    "require_minimum_savings": true,
    "minimum_savings_balance": 10000
  }
}
Available fields:
FieldTypeDescription
default_distribution_methodstringDistribution method: by_contribution, equal
min_pool_amountnumberMinimum amount to create dividend pool
require_minimum_savingsbooleanRequire minimum savings for eligibility
minimum_savings_balancenumberMinimum savings balance required
See: Dividends Overview

​
Immutable Settings

These fields are set at organization creation and cannot be changed via API:

​
Currency Code

Field: currencyCode Default: RWF (Rwandan Franc) Example values: RWF, USD, KES, TZS Why immutable: Changing currency would corrupt existing financial records. All transactions, balances, and reports are in this currency.

​
Amount Scale

Field: amountScale Default: 0 (whole numbers) Values:
  • 0 = Whole numbers (e.g., 10000)
  • 2 = Two decimal places (e.g., 10000.50)
Usage:
  • 0 for currencies without subdivisions (RWF)
  • 2 for currencies with cents (USD)
Why immutable: Changing decimal precision would corrupt amounts in database.

​
Timezone

Field: timezone Default: Africa/Kigali Example values: Africa/Kigali, Africa/Nairobi, Africa/Dar_es_Salaam, UTC Usage:
  • Transaction timestamps displayed in this timezone
  • Date range filters use this timezone
  • Report “as of” dates calculated in this timezone
Why immutable: Historical timestamps would become ambiguous if timezone changed.

​
Date Format

Field: dateFormat Default: DD/MM/YYYY Example values:
  • DD/MM/YYYY (10/06/2026)
  • MM/DD/YYYY (06/10/2026)
  • YYYY-MM-DD (2026-06-10)
Note: Currently stored in database but not actively used by backend. Display formatting handled by frontend.

​
Directional Rounding

Field: directionalRounding Default: false Values:
  • false = Standard rounding (0.5 rounds up)
  • true = Banker’s rounding (round to nearest even)
Note: Currently stored in database but not actively used. Rounding handled by quantizeByFlow function.

​
Read-Only Fields

Organization ID: id - System-generated UUID Numeric ID: numericId - Sequential organization number Organization Type: type - Always TONTINE Created At: createdAt - Organization creation timestamp Onboarding Completed: onboardingCompleted - Setup wizard status

​
Common Use Cases

​
Change Organization Name

API call: 
curl -X PUT "/organizations/org-abc123" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agatabo Cooperative XYZ"
  }'
Result: Name changes immediately throughout application.

​
Enable Email Notifications

API call: 
curl -X PUT "/organizations/org-abc123/settings" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "enableEmail": true
  }'
Verify: Members have email addresses in profiles.

​
Switch from Monthly to Quarterly

Requirement: No periods closed yet (cannot change after closing). API call: 
curl -X PUT "/organizations/org-abc123/settings" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "accountingPeriod": "QUARTERLY"
  }'
If periods already closed: Error returned - contact support for migration.

​
Configure Loan Rules

API call: 
curl -X PUT "/organizations/org-abc123/settings" \
  -H "x-organization-id: org-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "loanSettings": {
      "min_loan_amount": 100000,
      "max_loan_amount": 10000000,
      "interest_rate": 12,
      "max_loan_percentage": 3.0
    }
  }'
Effect: Loan creation validates against these rules.

​
Best Practices

Configuring organization settings:Initial setup:
  • ✅ Set currency and amount scale correctly (immutable!)
  • ✅ Verify timezone matches physical location
  • ✅ Choose appropriate accounting period (monthly recommended)
  • ✅ Configure loan settings before disbursing first loan
  • ✅ Test notifications with your own email/phone
Ongoing management:
  • ✅ Limit settings:write permission to trusted administrators
  • ✅ Document custom configurations (loan/dividend settings)
  • ✅ Review audit logs after settings changes
  • ✅ Test settings in staging environment first (if available)
  • ✅ Communicate settings changes to organization members
Accounting period:
  • ✅ Choose period type before closing first period
  • ✅ Cannot change after periods closed (plan ahead)
  • ✅ Monthly provides best oversight for active organizations
  • ✅ Quarterly reduces admin burden for smaller groups
Loan/dividend settings:
  • ✅ Keep JSON configuration backed up
  • ✅ Validate JSON before saving (invalid JSON breaks features)
  • ✅ Use percentage fields correctly (10% = enter 10, not 0.1)
  • ✅ Modify with technical assistance if unsure

​
Troubleshooting

Q: Can’t edit organization settings A: Check:
  • You have settings:write permission
  • You’re logged in as organization user
  • Correct organization selected via x-organization-id header
Contact administrator to grant permission.
Q: Currency or decimal precision wrong A: If no transactions recorded:
  • Contact system administrator to manually update database
  • Risky - backup first
If transactions already recorded:
  • Cannot change (would corrupt existing data)
  • May need to export, create new organization, re-import
  • Contact support for migration assistance
Q: Accounting period change rejected A: Error: “Cannot change accounting period after closing periods” Cause: You’ve already closed at least one period. Solution: Cannot change. Accounting period is locked after first close. Contact support if absolutely necessary.
Q: Notifications not sending A: Check:
  • enableEmail or enableSms is true
  • Members have valid email addresses/phone numbers
  • Email/SMS service configured by administrator
  • Check spam folder (emails)
  • Verify SMS credits available (SMS)
Q: Loan settings not applying A: Verify:
  • Settings saved successfully (check response)
  • JSON is valid (no syntax errors)
  • Percentage fields use correct values
  • Refresh application to load new settings
Debug: View current settings with GET /organizations/{id} to confirm they saved.
Q: Can’t change timezone A: Timezone is immutable. Cannot be changed after organization creation. Why: Historical transaction timestamps would become ambiguous. Workaround: None. Timezone is permanent.

Period Closing

Accounting period management

Audit Trail

Track settings changes

Permissions

Manage settings:write access

User Preferences

Individual user settings