Organization Settings: Configure Your Tontine on Agatabo

Organization Settings give you precise control over how your tontine operates. You can update your display name, choose how often you close your books, decide whether Agatabo sends email or SMS alerts to members, and fine-tune the rules that govern loan eligibility and dividend distribution. A separate group of fields — currency, timezone, decimal precision, and a few others — is locked after organization creation to preserve the integrity of your historical financial records. This page covers both groups in full.

You need settings:read to view these settings and settings:write to change them. Contact an administrator if you need either permission granted.

Configurable Settings

The following fields can be updated at any time through the Agatabo UI or the PUT /organizations/{id}/settings API endpoint (except where noted).

Organization Name

Property	Value
Field	`name`
Type	String
API endpoint	`PUT /organizations/{organizationId}`

Your organization’s display name appears on dashboards, reports, and all member-facing communications. Update it whenever your group formally changes its name.

{ "name": "Agatabo Cooperative XYZ" }

Accounting Period Type

Property	Value
Field	`accountingPeriod`
Type	Enum: `MONTHLY`, `QUARTERLY`, `YEARLY`
Default	`MONTHLY`

The accounting period type determines how frequently you close your books and produce a formal income statement. Choose the cadence that matches your group’s activity level.

Value	Recommended for
`MONTHLY`	Active organizations with regular transactions — provides the tightest oversight
`QUARTERLY`	Mid-size groups with moderate transaction volume
`YEARLY`	Low-activity organizations or groups just starting out

You can change the accounting period type only before you close your first period. Once any period has been closed, this field is locked. Plan your period type carefully during initial setup — contact support if you need to change it after the fact.

If you try to change this setting after closing a period, the API returns:

{
  "message": "Cannot change accounting period after closing periods. Please contact support."
}

Email Notifications

Property	Value
Field	`enableEmail`
Type	Boolean
Default	`true`

When enabled, Agatabo sends email notifications to members for loan approvals, payment reminders, payment confirmations, contribution reminders, and general announcements. All members with a valid email address on their profile receive these messages. Prerequisites: Members must have email addresses stored in their profiles, and the email service must be configured by your system administrator.

{ "enableEmail": true }

SMS Notifications

Property	Value
Field	`enableSms`
Type	Boolean
Default	`false`

When enabled, Agatabo sends SMS messages for loan approvals, payment reminders, and urgent alerts. SMS messages incur per-message charges through the Pindo SMS service. Prerequisites: Members must have phone numbers in their profiles, the Pindo integration must be configured, and sufficient SMS credits must be available.

{ "enableSms": true }

Test both notification channels with your own account before relying on them for member communications. Send a test loan approval to verify delivery end-to-end.

Loan Settings

The loanSettings object controls every policy parameter that Agatabo checks when a loan is requested or disbursed. Pass the entire object when updating — omitted fields retain their current values.

Field	Type	Description
`min_loan_amount`	Number	Minimum loan amount a member can request
`max_loan_amount`	Number	Maximum loan amount a member can request
`interest_rate`	Number	Default annualized interest rate (enter as a percentage, e.g., `10` for 10%)
`coverage_ratio`	Number	Required loan-to-collateral ratio (e.g., `1.2` means collateral must be 1.2× the loan)
`min_savings_ratio`	Number	Member’s savings balance must be at least this fraction of the requested loan amount
`max_loan_percentage`	Number	Maximum loan amount expressed as a multiple of the member’s savings balance
`disbursement_fee_percentage`	Number	Fee charged at disbursement as a percentage of the loan amount

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

Percentage fields are entered as human-readable percentages (e.g., 10 for 10%), and Agatabo stores them as decimals internally. Invalid or inconsistent loan settings can prevent loan creation entirely — validate your JSON and confirm the logic before saving.

Dividend Settings

The dividendSettings object governs how surplus income is distributed to members at the end of a cycle.

Field	Type	Description
`default_distribution_method`	String	How to divide the dividend pool: `by_contribution` (proportional to savings) or `equal` (equal share per member)
`min_pool_amount`	Number	Minimum total amount required before a dividend pool can be created
`require_minimum_savings`	Boolean	Whether members must maintain a minimum savings balance to receive dividends
`minimum_savings_balance`	Number	The minimum savings balance a member must hold to be eligible (applies when `require_minimum_savings` is `true`)

Example configuration:

{
  "dividendSettings": {
    "default_distribution_method": "by_contribution",
    "min_pool_amount": 100000,
    "require_minimum_savings": true,
    "minimum_savings_balance": 10000
  }
}

Immutable Settings

The following fields are fixed at organization creation and cannot be changed through the API or the UI. Attempting to update them has no effect.

If any immutable setting was configured incorrectly and no transactions have been recorded yet, contact your system administrator immediately. Once financial records exist, these values are permanently locked — changing them would corrupt every monetary amount, timestamp, and calculation in your database.

Setting	Field	Default	Why It Cannot Change
Currency	`currencyCode`	`RWF`	Every transaction, balance, and report is denominated in this currency. Changing it would corrupt all existing monetary values.
Amount scale	`amountScale`	`0` (whole numbers)	`0` = no decimal places (RWF); `2` = two decimal places (USD). Stored amounts would become ambiguous if precision changed mid-operation.
Timezone	`timezone`	`Africa/Kigali`	All historical timestamps are anchored to this timezone. Changing it would make timestamps ambiguous retroactively.
Date format	`dateFormat`	`DD/MM/YYYY`	Display consistency depends on a stable, single format across all records.
Directional rounding	`directionalRounding`	`false`	`false` = standard rounding; `true` = banker’s rounding. Rounding behavior is established at creation to keep calculations consistent.

Read-Only System Fields

These fields are auto-generated by Agatabo and cannot be modified by any user:

Field	Description
`id`	System-generated UUID that uniquely identifies your organization
`numericId`	Sequential numeric identifier assigned at creation
`type`	Always `TONTINE` — determines core system behavior
`createdAt`	Timestamp when the organization was first created
`onboardingCompleted`	Tracks whether the setup wizard has been finished

Retrieve Current Settings

To inspect your current configuration, call:

GET /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}

Response:

{
  "message": "Organization details retrieved successfully",
  "data": {
    "id": "org-abc123",
    "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 Settings

Send only the fields you want to change. All other settings remain untouched.

PUT /organizations/{organizationId}/settings
Headers:
  x-organization-id: {organizationId}
Content-Type: application/json

{
  "accountingPeriod": "MONTHLY",
  "enableEmail": true,
  "enableSms": false,
  "loanSettings": { "..." : "..." },
  "dividendSettings": { "..." : "..." }
}

Field	Type	Required	Description
`accountingPeriod`	Enum	No	`MONTHLY`, `QUARTERLY`, or `YEARLY` — locked after first period close
`enableEmail`	Boolean	No	Turn email notifications on or off
`enableSms`	Boolean	No	Turn SMS notifications on or off
`loanSettings`	Object	No	Full loan policy object (see fields above)
`dividendSettings`	Object	No	Full dividend policy object (see fields above)

Successful response:

{ "message": "Organization settings updated successfully" }

Troubleshooting

I can't edit organization settings

Confirm you hold the settings:write permission. Open the Audit Logs or ask your administrator to check your current role grants. If you need access, ask an administrator to assign a role that includes settings:write.

The accounting period change was rejected

This error appears when at least one period has already been closed: “Cannot change accounting period after closing periods.” The field is permanently locked after the first period close. Contact support if a migration is absolutely necessary.

Notifications aren't being delivered

Check that enableEmail or enableSms is set to true, members have valid contact details in their profiles, and the relevant service (email relay or Pindo SMS) has been configured by your system administrator. For email, check recipients’ spam folders. For SMS, confirm that credits are available.

Loan settings don't appear to be taking effect

Retrieve current settings with GET /organizations/{id} to confirm the values were saved correctly. Verify that your JSON is valid (no syntax errors), that percentage fields contain the intended values, and refresh the application to load the updated configuration.

Period Closing

Understand how accounting periods are closed and why the accounting period type must be chosen carefully.

Audit Trail

Review the permanent log of every settings change your organization has ever made.

Permissions

Control who holds settings:write and other sensitive permissions in your organization.

Settings Overview

Return to the top-level overview of all settings sections.

​Configurable Settings

​Organization Name

​Accounting Period Type

​Email Notifications

​SMS Notifications

​Loan Settings

​Dividend Settings

​Immutable Settings

​Read-Only System Fields

​Retrieve Current Settings

​Update Settings

​Troubleshooting

Period Closing

Audit Trail

Permissions

Settings Overview

Configurable Settings

Organization Name

Accounting Period Type

Email Notifications

SMS Notifications

Loan Settings

Dividend Settings

Immutable Settings

Read-Only System Fields

Retrieve Current Settings

Update Settings

Troubleshooting