System Configuration: Tune Your Group's Financial Rules

The system configuration API lets you read your group’s current financial rules at any time without authentication, and update those rules as an admin with a single PUT request. Every field is optional on update — only the fields you include are changed, and the full updated configuration is returned immediately. Changes persist to the database and take effect across all connected devices without a restart.

GET /api/config

Returns the current system configuration. This endpoint is public — no authentication is required.

GET /api/config requires no Authorization header. You can call it from an unauthenticated client to display group settings on onboarding screens or public-facing pages.

Response

See the full SystemConfig fields table below.

curl --request GET \
  --url "https://api.saveapp.io/api/config"

Sample response

{
  "loan_interest_rate": 10.0,
  "max_loan_multiplier": 3.0,
  "max_loan_limit": 5000000.0,
  "payout_amount": 500000.0,
  "retention_percentage": 10.0,
  "late_penalty_rate": 0.5,
  "contribution_amount": 50000.0,
  "max_loan_duration": 12,
  "weight_on_time_payment": 5,
  "weight_late_payment": -10,
  "weight_missed_payment": -20,
  "weight_loan_repaid_on_time": 15,
  "weight_loan_repaid_late": -5,
  "weight_loan_defaulted": -50,
  "weight_cycle_completed": 10,
  "min_credit_score": 300,
  "max_credit_score": 850,
  "starting_credit_score": 500,
  "frequency": "Monthly",
  "recipients": 1,
  "loan_late_fee": 50.0,
  "start_date": "Oct 1, 2023",
  "automatic_payouts": true,
  "scheduled_contributions": true,
  "smart_roundups": false,
  "automated_cycle": true,
  "loan_requests": true
}

PUT /api/config

Updates system configuration. Requires an admin JWT. Only the fields present in the request body are modified — omitted fields retain their current values. Returns the full updated SystemConfig object.

To temporarily pause loan requests while your group resolves a funding shortfall, set loan_requests to false. This disables the loan request flow for all members without affecting any loans already in progress.

Request body

All fields are optional. Include only the fields you want to change.

Financial rules

float

Annual interest rate applied to loans, expressed as a percentage. Must be between 0 and 100.

float

Maximum loan amount expressed as a multiple of the member’s savings. For example, 3 means a member can borrow up to three times what they have contributed. Must be >= 0.

float

Absolute maximum loan amount in UGX, regardless of savings multiplier. Must be >= 0.

float

Maximum amount disbursed per payout execution, in UGX. Must be >= 0.

float

Percentage of the payout amount retained in the group fund rather than disbursed. Must be between 0 and 100.

float

Daily penalty rate applied to overdue loan balances, expressed as a percentage. Must be >= 0.

float

Fixed contribution amount required from each member per cycle, in UGX. Must be >= 0.

integer

Maximum loan term in months. Must be >= 0.

Credit score weights

These values are added to or subtracted from a member’s credit score when the corresponding event occurs.

integer

default:"5"

Points added when a contribution is made on time.

integer

default:"-10"

Points added (negative) when a contribution is made after the due date.

integer

default:"-20"

Points added (negative) when a contribution is missed entirely.

integer

default:"15"

Points added when a loan is fully repaid on or before the due date.

integer

default:"-5"

Points added (negative) when a loan is repaid after the due date.

integer

default:"-50"

Points added (negative) when a loan is marked as defaulted.

integer

default:"10"

Points added when a member completes a full group cycle.

Credit score boundaries

integer

default:"300"

Floor value for the credit score. A score cannot fall below this number.

integer

default:"850"

Ceiling value for the credit score. A score cannot rise above this number.

integer

default:"500"

Credit score assigned to every new member when their account is created.

Cycle and chama settings

string

default:"Monthly"

Contribution and payout cycle frequency (e.g., "Monthly", "Weekly").

integer

default:"1"

Number of members who receive a payout per cycle execution.

float

default:"50.0"

Fixed late fee charged per overdue loan repayment event, in UGX.

string

default:"Oct 1, 2023"

The date the current cycle started, used as the reference point for scheduling. Accepts a human-readable date string (e.g., "Jan 1, 2025").

boolean

default:"true"

When true, payouts are executed automatically by the scheduler. When false, an admin must trigger each payout manually.

boolean

default:"true"

When true, the system sends reminders and tracks contribution due dates based on the configured frequency and start_date.

boolean

default:"false"

When true, member transactions are rounded up and the difference is added as a micro-contribution to the group fund.

boolean

default:"true"

When true, the system automatically advances the group to the next cycle when all conditions are met.

boolean

default:"true"

When true, members can submit new loan requests. Set to false to pause the loan request flow for all members.

Response

Returns the full updated SystemConfig object. See the sample response under GET /api/config.

curl --request PUT \
  --url "https://api.saveapp.io/api/config" \
  --header "Authorization: Bearer <admin_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "loan_interest_rate": 12.5,
    "max_loan_limit": 3000000.0
  }'

curl --request PUT \
  --url "https://api.saveapp.io/api/config" \
  --header "Authorization: Bearer <admin_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "loan_requests": false
  }'

curl --request PUT \
  --url "https://api.saveapp.io/api/config" \
  --header "Authorization: Bearer <admin_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "weight_on_time_payment": 8,
    "weight_missed_payment": -25,
    "weight_loan_defaulted": -60
  }'

Error responses

Status	Condition
`400 Bad Request`	A field value is out of its valid range (e.g., `loan_interest_rate` outside 0–100, or a negative amount field).
`401 Unauthorized`	No valid `Authorization` header was provided.
`403 Forbidden`	The authenticated user does not have the `admin` role.

Notifications

GET /api/notifications

Returns all notifications for the authenticated user, ordered by created_at descending. Requires authentication.

Response

Returns an array of NotificationResponse objects.

string

UUID of the notification.

string

Short title of the notification.

string

Full notification body text.

string

Category of the notification (e.g., "loan", "contribution", "payout").

boolean

true if the user has read this notification.

datetime

ISO 8601 timestamp of when the notification was created.

curl --request GET \
  --url "https://api.saveapp.io/api/notifications" \
  --header "Authorization: Bearer <token>"

POST /api/notifications//read

Marks a single notification as read. The notification must belong to the authenticated user. Returns 404 if the ID is not found or belongs to a different user.

string

required

UUID of the notification to mark as read.

Response

boolean

true when the notification was successfully marked as read.

string

Confirmation message: "Notification marked as read".

curl --request POST \
  --url "https://api.saveapp.io/api/notifications/a1b2c3d4-e5f6-7890-abcd-ef1234567890/read" \
  --header "Authorization: Bearer <token>"

POST /api/notifications/read-all

Marks all unread notifications for the authenticated user as read in a single operation.

Response

boolean

true when all notifications were successfully updated.

string

Confirmation message: "All notifications marked as read".

curl --request POST \
  --url "https://api.saveapp.io/api/notifications/read-all" \
  --header "Authorization: Bearer <token>"

POST /api/notifications/update-token

Registers or replaces the FCM (Firebase Cloud Messaging) push token for the authenticated user’s device. Call this endpoint after obtaining a fresh token from the Firebase SDK — typically on app launch and whenever onTokenRefresh fires.

Request body

string

required

The FCM device token obtained from the Firebase SDK. Must be at least 1 character.

Response

boolean

true when the token was saved successfully.

string

Confirmation message: "FCM token updated successfully".

curl --request POST \
  --url "https://api.saveapp.io/api/notifications/update-token" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "token": "fXpN3k...FCM_TOKEN"
  }'

Sample response (all notification endpoints)

{
  "success": true,
  "message": "FCM token updated successfully"
}

Auth

Members

Loans

Transactions & Payouts

Analytics & Config

System Configuration: Tune Your Group's Financial Rules

GET /api/config

Response

PUT /api/config

Request body

Financial rules

Credit score weights

Credit score boundaries

Cycle and chama settings

Response

Error responses

Notifications

GET /api/notifications

Response

POST /api/notifications//read

Response

POST /api/notifications/read-all

Response

POST /api/notifications/update-token

Request body

Response

​GET /api/config

​Response

​PUT /api/config

​Request body

​Financial rules

​Credit score weights

​Credit score boundaries

​Cycle and chama settings

​Response

​Error responses

​Notifications

​GET /api/notifications

​Response

​POST /api/notifications//read

​Response

​POST /api/notifications/read-all

​Response

​POST /api/notifications/update-token

​Request body

​Response

GET /api/config

Response

PUT /api/config

Request body

Financial rules

Credit score weights

Credit score boundaries

Cycle and chama settings

Response

Error responses

Notifications

GET /api/notifications

Response

POST /api/notifications//read

Response

POST /api/notifications/read-all

Response

POST /api/notifications/update-token

Request body

Response