New Member Onboarding: Complete 7-Stage Workflow

Bringing a new member into your tontine requires more than collecting a deposit — it means verifying identity, provisioning the right system access, creating the savings ledger, and ensuring the member understands their obligations. This guide walks you through every stage of that journey, from the first conversation to full activation, with API calls, checklists, and a recommended timeline.

System behavior to know upfront: When you assign the “member” role to an organization user, Agatabo automatically creates a savings ledger account for that person. No savings ledger means no deposits or loans. Role assignment is therefore the single most critical step in the entire workflow — do not skip it.

Workflow Stages

Recruitment → Verification → System Registration → Role Assignment → Financial Setup → Orientation → Activation

Stage 1: Recruitment & Application

Introduce the candidate to your organization

Explain the tontine model clearly before the candidate commits to anything. Cover:

The purpose of the group and how pooled savings work
Contribution requirements — amount, frequency, and due dates
Loan eligibility rules and interest rates
Dividend distribution and how profits are shared
Bylaws, governance structure, and member responsibilities

Answer all questions honestly. A member who joins without understanding these rules is far more likely to default or disengage.

Collect the membership application

Ask the candidate to submit a completed membership form with the following:

Document	Required?	Notes
Government-issued ID	Yes	For identity verification
Proof of address	Org. policy	Check your bylaws
Recent photograph	Yes	For member file
Reference from existing member	Org. policy	If required by bylaws
Application fee payment	Org. policy	If your org. charges one

Information to capture:

Full legal name
Phone number (required — used for login and SMS notifications)
Email address (optional — used for login and email notifications)
Residential address (for records; not stored in Agatabo)
Emergency contact

Stage 2: Verification & Approval

Verify the candidate's information

Before any committee vote, confirm that the information on the application is accurate:

Identity — check the government ID against the application name
Phone number — place a test call or send a test SMS
Email address — send a verification message
References — contact the recommending member if your policy requires it

Assess eligibility

Confirm the candidate meets your organization’s membership criteria:

Meets minimum age requirement (typically 18+)
Has a stable income or livelihood
Has no outstanding debts to the organization from prior membership
Has no conflicts of interest with current members or officers
Can commit to the contribution schedule

Hold the committee review and vote

Present the candidate to the membership committee. Record the outcome:

Conduct the vote according to your bylaws (simple majority, two-thirds, etc.)
Document the decision in the official meeting minutes
Note the date, voting members present, and vote tally

Notify the candidate

Approved
Rejected

Send a welcome letter or email within 48 hours that includes:

Confirmation of approval and join date
Next steps (system registration and orientation schedule)
Initial contribution requirements and payment methods
Treasurer contact details

Pre-registration checklist:

✅ Identity verified against government ID
✅ Phone and email confirmed working
✅ References checked (if required by policy)
✅ Committee vote recorded with majority approval
✅ Decision documented in meeting minutes
✅ No outstanding debts to the organization

Stage 3: System Registration

Who: Administrator with organization_users:write permission Create the organization user in Agatabo. This links the person to your organization and triggers the invitation flow so they can set up their password.

Create the Organization User

Endpoint: POST /organization-users

POST /organization-users
Headers:
  x-organization-id: {organizationId}
Body:
{
  "newUser": {
    "name": "Jane Smith",
    "phone": "+250781234567",
    "email": "jane.smith@example.com"
  },
  "joinDate": "2026-06-01",
  "sendInvitation": true
}

Request fields:

Field	Type	Required	Description
`newUser`	object	Yes (if no `userId`)	Details for a brand-new user
`newUser.name`	string	Yes	Full legal name
`newUser.phone`	string	Yes	Phone in international format (+250…)
`newUser.email`	string	No	Email address
`userId`	string	No	Supply this instead of `newUser` if the person already has an Agatabo account
`joinDate`	string	Yes	ISO 8601 date (e.g., `2026-06-01`)
`sendInvitation`	boolean	No	Default: `true` — sends email or SMS

What Agatabo does automatically:

Checks whether the email or phone already belongs to an existing Agatabo user. If yes, it links that account; if no, it creates a new one.
Creates an organization user record linking the person to your organization, sets the join date, and marks the account active.
Sends an invitation — by email if an address was provided, by SMS if the user has only a phone number, or generates a manual link if neither is available.

Sample response (201 Created):

{
  "message": "Organization user added and invitation sent",
  "data": {
    "organizationUser": {
      "id": "orguser-123",
      "userId": "user-456",
      "organizationId": "org-abc",
      "isActive": true,
      "joinDate": "2026-06-01T00:00:00.000Z",
      "user": {
        "id": "user-456",
        "name": "Jane Smith",
        "phone": "+250781234567",
        "email": "jane.smith@example.com"
      }
    },
    "invitation": {
      "invitationId": "inv-789",
      "inviteLink": "https://app.agatabo.com/invite?token=xyz...",
      "expiresAt": "2026-06-04T00:00:00.000Z",
      "deliveryMode": "sent",
      "channel": "EMAIL"
    }
  }
}

Invitation delivery modes:

Mode	Meaning
`sent`	Email or SMS delivered successfully
`manual_only`	No email or phone available — share the link in person

What the Member Receives

Email (if email provided)
SMS (phone only)

Subject: You’ve been invited to [Organization Name]

You've been invited to join [Organization Name] on Agatabo.

Click here to set your password and activate your account:
[Secure Link]

This link expires in 72 hours.

You've been invited to [Organization Name] on Agatabo.
Set your password: [Short Link]
Expires in 72 hours.

Once the member clicks the link, sets a password (minimum 6 characters), and logs in, their account is active.

Stage 4: Role Assignment

Who: Administrator with organization_user_roles:assign permission

You must assign the “member” role before you can record any deposits or issue any loans for this person. The role assignment triggers automatic creation of the savings ledger account. Without it, all financial operations will fail.

Endpoint: POST /organization-users/{organizationUserId}/role-assignments

POST /organization-users/orguser-123/role-assignments
Headers:
  x-organization-id: {organizationId}
Body:
{
  "roleDefinitionId": "role-member-456",
  "assignedAt": "2026-06-01"
}

What happens when you assign the “member” role:

Savings ledger account created — a SAVINGS liability account is provisioned automatically and linked to the organization user. The balance starts at zero.
Loan eligibility unlocked — the member can now apply for and receive loans.
Member self-service enabled — the member can view their savings balance, loan status, and full account statement.

Sample response (201 Created):

{
  "id": "assignment-789",
  "organizationUserId": "orguser-123",
  "roleDefinitionId": "role-member-456",
  "assignedAt": "2026-06-01T00:00:00.000Z",
  "createdAt": "2026-06-13T10:30:00.000Z"
}

Verify the savings account was created:

GET /organization-users/orguser-123
Headers:
  x-organization-id: {organizationId}

The response should include a non-null savingsLedgerAccountId:

{
  "savingsLedgerAccountId": "acc-123",
  "savingsLedgerAccount": {
    "id": "acc-123",
    "role": "SAVINGS",
    "name": "Jane Smith - Savings"
  }
}

If savingsLedgerAccountId is null, do not proceed — see the Savings account not created accordion below.

Stage 5: Financial Setup

Who: Treasurer with savings:write permission Collect the member’s initial contribution before they attend orientation. Most organizations require some combination of a one-time membership fee, a minimum opening savings deposit, and share capital.

Record the Initial Deposit

Endpoint: POST /savings

POST /savings
Headers:
  x-organization-id: {organizationId}
  x-idempotency-key: {unique-key}
Body:
{
  "organizationUserId": "orguser-123",
  "amount": 35000,
  "transactionDate": "2026-06-01",
  "paymentMethod": "CASH",
  "description": "Initial membership deposit: 5K entry fee + 10K savings + 20K shares"
}

After this call succeeds:

Jane’s savings account is credited 35,000 RWF
The organization’s cash account is debited 35,000 RWF
A journal entry is created automatically
A receipt is generated and available via the API

Print the receipt and hand it to the member. File a copy in their member folder.

Record the Entry Fee Separately (Optional)

If your organization tracks entry fees in a dedicated account rather than bundling them into the savings deposit, use the entry fee endpoint:

POST /organization-users/orguser-123/entry-fee
Headers:
  x-organization-id: {organizationId}
  x-idempotency-key: {unique-key}
Body:
{
  "amount": 5000,
  "transactionDate": "2026-06-01",
  "paymentMethod": "CASH",
  "description": "One-time membership entry fee"
}

The entry fee endpoint requires the “member” role to already be assigned. If you see an error, confirm that Stage 4 completed successfully.

Stage 6: Member Orientation

Who: Board member, Treasurer, or Training Coordinator Conduct a 1–2 hour orientation session before the member makes their first regular contribution. This prevents misunderstandings that cause missed payments or loan defaults later.

Explain financial operations

Walk through day-to-day financial mechanics:

Contributions — amount, frequency, due dates, acceptable payment methods
Late payment penalties — how they are calculated and when they apply
Savings withdrawals — whether allowed, under what conditions, and the process
Loans — eligibility requirements, application process, interest rates, repayment terms, and penalties for default
Dividends — how profit is calculated, distribution frequency, eligibility, and any tax implications

Demonstrate the Agatabo member portal

Sit with the member at a device and walk through each screen:

Logging in with their email or phone number and password
Viewing current savings balance
Browsing deposit and payment history
Checking loan eligibility and outstanding balance
Downloading or viewing their account statement
Updating profile information and resetting their password

Confirm the member can log in successfully before you end this step.

Review bylaws and governance

Cover the member’s rights and responsibilities:

Voting procedures and quorum requirements
Meeting attendance expectations
Committee structure and how to get involved
Exit and withdrawal procedures, including refund of savings and shares
Confidentiality obligations and dispute resolution process

Distribute orientation materials

Hand the member the following before they leave:

Printed or digital copy of the bylaws
Contribution schedule with due dates for the next 12 months
Loan application form (if your process is paper-based)
Treasurer and administrator contact information
Written Agatabo login instructions
Emergency or support contact numbers

Orientation sign-off checklist:

✅ Member understands contribution requirements and due dates
✅ Member knows loan eligibility rules and process
✅ Member logged into Agatabo successfully during session
✅ Member signed the membership agreement
✅ Member received a copy of the bylaws
✅ Member knows who to contact with questions

Stage 7: Activation & Monitoring

Who: Treasurer, Membership Coordinator

Add to contribution tracking

Note the member’s first contribution due date in your tracking system
Add them to your SMS or email reminder list
Document their expected contribution frequency (monthly, quarterly, etc.)
Schedule a follow-up call for one week after joining

Create the member file

Assemble a physical or digital folder containing:

Completed membership application form
Copy of verified government ID
Signed bylaws acknowledgment
Initial deposit receipt
Orientation attendance record
Committee approval minutes
Any signed guarantee or collateral agreements

Update the member register

Add the member to your official member list
Increment the total member count
Record the join date for anniversary tracking
Assign a member number if your organization uses one

Announce the new member

If your bylaws require it:

Announce at the next general meeting
Send a welcome message to the full membership
Introduce the new member to key personnel (treasurer, committee chairs)

First 90 Days: Monitoring for Early Success

Track these signals during the first three months to catch problems before they escalate:

Signal	Frequency	Action if Missing
Contribution consistency	Monthly	Follow up immediately on first missed payment
Meeting attendance	Per meeting	Reach out after second absence
Agatabo login activity	Weekly check	Offer technical support
Questions or concerns raised	Ongoing	Respond within 24 hours

Pair every new member with an experienced “buddy” member for their first three months. Buddy-system programs consistently reduce early dropout rates.

Complete Onboarding Checklist

Pre-Registration

✅ Membership application received and complete
✅ Identity documents verified (government ID checked)
✅ References verified (if policy requires)
✅ Committee approval obtained and vote recorded
✅ Approval documented in committee minutes

System Registration

✅ Organization user created in Agatabo (POST /organization-users)
✅ Invitation sent — email, SMS, or manual link shared
✅ Member confirmed account activation (can log in)
✅ “Member” role assigned — this is the critical step that unlocks all financial operations
✅ Savings ledger account confirmed (check savingsLedgerAccountId via GET /organization-users/{id})

Financial Setup

✅ Initial contribution collected and verified
✅ Deposit recorded in Agatabo (POST /savings)
✅ Receipt printed and issued to member
✅ Member’s savings balance displays correctly in the system

Orientation

✅ Orientation session completed (1–2 hours)
✅ Bylaws provided and explained
✅ Agatabo system demonstrated — member navigated it successfully
✅ Contribution schedule handed over
✅ Membership agreement signed

Activation

✅ Member file created (physical or digital)
✅ Member added to contribution reminder list
✅ Official member register updated
✅ Welcome announcement made (if required by bylaws)
✅ First contribution due date confirmed and scheduled

Recommended Timeline

Day	Activity
Day 1	Candidate submits application with all required documents
Days 3–5	Verification of identity, phone, email, and references
Day 7	Committee meeting — membership approval vote
Day 8	Create organization user in Agatabo; send invitation
Day 9	Member receives email or SMS, sets password, activates account
Day 9	Assign “member” role — savings ledger account created automatically
Day 10	Collect initial contribution; record deposit in Agatabo
Day 11	Orientation session (1–2 hours)
Day 12	Member fully active — first regular contribution due date scheduled

Total elapsed time: 10–14 days from application to full activation

Common Issues

The invitation email was never received

Likely causes:

Email address was entered with a typo
Message landed in the member’s spam or junk folder
The 72-hour invitation link has expired
Your organization’s email service is not configured

What to do:

Ask the member to check their spam folder first.
Resend the invitation: GET /organization-users/me/pending-invitation-link.
If the email address is wrong, correct it and resend.
If the member has no email, fall back to SMS (phone-only login).
As a last resort, generate a manual link and share it in person.

Cannot record a deposit for the new member

Error message: "Savings can only be recorded for organization users with member role"Cause: The “member” role has not been assigned yet — or the assignment was to the wrong role definition.What to do:

Assign the correct member role: POST /organization-users/{id}/role-assignments.
Confirm the savings ledger account was created: GET /organization-users/{id} — look for a non-null savingsLedgerAccountId.
Retry the deposit: POST /savings.

Member joins mid-month — how do I handle contributions?

You have three options:Option A — Full contribution immediately (recommended): The member pays the full monthly amount on their join date. This is the simplest approach for bookkeeping and aligns their schedule with the calendar month.Option B — Pro-rated first contribution: Calculate the pro-rated amount: (days remaining in month ÷ total days in month) × monthly amount. Example: join on June 15, monthly contribution = 10,000 RWF → pro-rated = (15 ÷ 30) × 10,000 = 5,000 RWF. Full amount due from the following month onward.Option C — Skip the first month: The member starts contributing next month. Simpler, but delays their savings accumulation.We recommend Option A for clarity and consistency across all members.

Member cannot make the required initial deposit

Option 1 — Delay activation (recommended): Hold the member in a pending state until the deposit is collected. This maintains your organization’s standards consistently.Option 2 — Allow an installment plan: Accept a partial deposit (e.g., 50% now, 50% next month) and activate after the first payment. Document the agreement in writing and the committee minutes.Option 3 — Waive the requirement: The committee may vote to waive the deposit on a case-by-case basis. This must be recorded in minutes and applied consistently to avoid the appearance of favoritism.

Savings account was not created after role assignment

Expected behavior: The savings ledger account is created automatically when you assign the “member” role.Diagnostic steps:

Verify the role assignment succeeded: GET /organization-users/{id}/role-assignments. Confirm the record exists.
Verify you assigned the correct role: the role must have key = "member" — not a custom role with a similar name.
Check the organization user record: GET /organization-users/{id}. The savingsLedgerAccountId field should be non-null.
If the account is still missing after confirming the correct role was assigned, contact Agatabo support for manual resolution.

Member lives far away and cannot attend in person

Before approving a remote member, confirm:

Can they attend quarterly meetings (video call acceptable)?
How will they submit contributions? (mobile money and bank transfer are supported)
Can they satisfy large loan requirements with remote verification?
Are they willing to participate in governance remotely?

If you approve a remote member, require a video call orientation in place of in-person, set up mobile money for contributions, and document your remote participation policy so it applies equally to all remote members.

Inviting Members

Understand the permissions required for each onboarding step

Recording Deposits

Move directly to the loan workflow once the member is active

Idempotency

Prevent duplicate deposits during the financial setup stage

Permissions Matrix

Confirm which roles your admin and treasurer accounts need

​Workflow Stages

​Stage 1: Recruitment & Application

​Stage 2: Verification & Approval

​Stage 3: System Registration

​Create the Organization User

​What the Member Receives

​Stage 4: Role Assignment

​Stage 5: Financial Setup

​Record the Initial Deposit

​Record the Entry Fee Separately (Optional)

​Stage 6: Member Orientation

​Stage 7: Activation & Monitoring

​First 90 Days: Monitoring for Early Success

​Complete Onboarding Checklist

​Pre-Registration

​System Registration

​Financial Setup

​Orientation

​Activation

​Recommended Timeline

​Common Issues

Inviting Members

Recording Deposits

Idempotency

Permissions Matrix

Workflow Stages

Stage 1: Recruitment & Application

Stage 2: Verification & Approval

Stage 3: System Registration

Create the Organization User

What the Member Receives

Stage 4: Role Assignment

Stage 5: Financial Setup

Record the Initial Deposit

Record the Entry Fee Separately (Optional)

Stage 6: Member Orientation

Stage 7: Activation & Monitoring

First 90 Days: Monitoring for Early Success

Complete Onboarding Checklist

Pre-Registration

System Registration

Financial Setup

Orientation

Activation

Recommended Timeline

Common Issues