Skip to main content
A group in Save App is a named savings circle — a chama — where a set of people contribute money together over recurring cycles and take turns receiving payouts. Every account belongs to exactly one group, identified by a group_name. Within that group there are two distinct roles: admin and member. Understanding these roles and how member status works is essential before interacting with any other part of the API.

​
Roles

Unanimous approval required. Loans, contribution transactions, and payouts each require approval from all admins currently in the group before they are executed. If your group has three admins, all three must approve before the operation proceeds.

​
The Group Creator

The first admin to register a group becomes its creator (is_creator: true). The creator is a permanent role — it does not change when other admins are added or removed. Only the group creator can delete the group entirely.

​
Member Status

Every user record carries a status field that reflects where they are in the onboarding flow. Only active members are included in cycle payout queues and contribution counts.

​
How Members Join

1

Admin registers the new member

An admin calls the member registration endpoint with the new person’s name and phone number. The system creates the account in pending status and issues a one-time password (OTP) to the phone number.
2

Admin shares the group name and phone number

The admin communicates the group name to the new member out of band (SMS, WhatsApp, or in person). These are the two pieces of information the member needs to start onboarding.
3

New member sets a password

Using the onboarding flow, the member calls POST /api/auth/onboarding/check-phone to confirm their account exists, then POST /api/auth/onboarding/set-password to choose a PIN. This transitions their status from pending to active.
4

Member is ready to participate

Once active, the member appears in future payout queues, their contributions are tracked, and their credit score starts accumulating history.

​
Multi-Admin Support

A group can have more than one admin. Additional admins are promoted from the member role by an existing admin (via the PUT /api/members/{member_id} endpoint with role: "admin"). Likewise, an admin can be demoted back to member. The group creator cannot be demoted.
Pending approvals that were created before the new admin joined do not retroactively require the new admin’s signature. Only approvals created after the promotion require all current admins to sign.
No. Each user account is scoped to a single group_name. To participate in two groups, a person would need two separate accounts with different phone numbers.
Suspending sets is_active to false. The member cannot log in, is excluded from new cycle payout queues, and their contributions are not counted toward cycle completion checks. Their historical data is preserved.