> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organization Settings

> Configure organization details and operational preferences

## Overview

**Organization Settings** control core configuration for your organization, including name, accounting period, notification preferences, and advanced loan/dividend rules.

<Note>
  **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.
</Note>

***

## API Endpoints

### Get Organization Settings

**Retrieve organization configuration:**

```http theme={null}
GET /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}
```

**Response:**

```json theme={null}
{
  "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:**

```http theme={null}
PUT /organizations/{organizationId}
Headers:
  x-organization-id: {organizationId}
Body:
{
  "name": "New Organization Name"
}
```

**Response:**

```json theme={null}
{
  "message": "Organization updated successfully",
  "data": {
    "id": "org-abc123",
    "name": "New Organization Name",
    ...
  }
}
```

***

### Update Organization Settings

**Update operational settings:**

```http theme={null}
PUT /organizations/{id}/settings
Headers:
  x-organization-id: {organizationId}
Body:
{
  "accountingPeriod": "MONTHLY",
  "enableEmail": true,
  "enableSms": false,
  "loanSettings": { ... },
  "dividendSettings": { ... }
}
```

**Request body fields:**

| Field              | Type    | Required | Description                                   |
| ------------------ | ------- | -------- | --------------------------------------------- |
| `accountingPeriod` | enum    | No       | Period type: `MONTHLY`, `QUARTERLY`, `YEARLY` |
| `enableEmail`      | boolean | No       | Enable email notifications                    |
| `enableSms`        | boolean | No       | Enable SMS notifications                      |
| `loanSettings`     | object  | No       | Loan policies and rules                       |
| `dividendSettings` | object  | No       | Dividend distribution settings                |

**Response:**

```json theme={null}
{
  "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}`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](/tontines/advanced/period-closing)

***

### Email Notifications

**Field**: `enableEmail`

**Type**: boolean

**Default**: `true`

**API**: `PUT /organizations/{id}/settings`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

| Field                         | Type   | Description                        |
| ----------------------------- | ------ | ---------------------------------- |
| `min_loan_amount`             | number | Minimum loan amount allowed        |
| `max_loan_amount`             | number | Maximum loan amount allowed        |
| `interest_rate`               | number | Default interest rate (percentage) |
| `coverage_ratio`              | number | Loan-to-collateral ratio           |
| `min_savings_ratio`           | number | Minimum savings as % of loan       |
| `max_loan_percentage`         | number | Max loan as multiple of savings    |
| `disbursement_fee_percentage` | number | Fee 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:**

```json theme={null}
{
  "dividendSettings": {
    "default_distribution_method": "by_contribution",
    "min_pool_amount": 100000,
    "require_minimum_savings": true,
    "minimum_savings_balance": 10000
  }
}
```

**Available fields:**

| Field                         | Type    | Description                                     |
| ----------------------------- | ------- | ----------------------------------------------- |
| `default_distribution_method` | string  | Distribution method: `by_contribution`, `equal` |
| `min_pool_amount`             | number  | Minimum amount to create dividend pool          |
| `require_minimum_savings`     | boolean | Require minimum savings for eligibility         |
| `minimum_savings_balance`     | number  | Minimum savings balance required                |

See: [Dividends Overview](/tontines/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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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

<Note>
  **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
</Note>

***

## 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.

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Period Closing" icon="lock" href="/tontines/advanced/period-closing">
    Accounting period management
  </Card>

  <Card title="Audit Trail" icon="file-magnifying-glass" href="/tontines/advanced/audit-trail">
    Track settings changes
  </Card>

  <Card title="Permissions" icon="shield" href="/tontines/settings/permissions">
    Manage settings:write access
  </Card>

  <Card title="User Preferences" icon="user-gear" href="/tontines/settings/user-preferences">
    Individual user settings
  </Card>
</CardGroup>