New Member Onboarding

Overview

The New Member Onboarding Workflow ensures new members are properly registered, trained, and integrated into the organization with complete documentation and system setup.

Key system behavior: When the “member” role is assigned to an organization user, the system automatically creates a savings ledger account for that user. This is required before recording deposits or issuing loans.

Workflow Stages

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

Stage 1: Recruitment & Application

Who: Existing members or Recruitment Committee Activities:

Introduce candidate to organization

Explain tontine concept and benefits
Describe contribution requirements (amount, frequency)
Share bylaws and membership rules
Answer candidate questions
Discuss loan eligibility and dividend distribution

Candidate expresses interest

Provides basic contact information
Attends informational meeting
Receives application materials

Application submission

Candidate fills out membership form
Provides required documents:
- Government ID (for identity verification)
- Proof of address (if required by organization)
- Recent photo
- Reference from existing member (if policy requires)
Pays application fee (if applicable)

Information collected:

Full legal name
Phone number (required - used for login and SMS)
Email address (optional - used for login and email notifications)
Residential address (for records, not stored in Agatabo system)
Emergency contact information
Reference from existing member (if policy requires)

Stage 2: Verification & Approval

Who: Membership Committee or Board Activities:

Verify candidate information

Confirm identity (check government ID)
Verify phone number (test call/SMS)
Verify email address (if provided)
Check references (if policy requires)

Assess eligibility

Meets age requirements? (typically 18+)
Has stable income/livelihood?
Recommended by existing member? (if required)
No conflicts of interest?
Can commit to contribution schedule?

Committee review

Present candidate to membership committee
Vote on membership approval
Document approval decision in meeting minutes

Notify candidate

If approved:

Send welcome letter/email with next steps
Provide orientation schedule
Explain initial contribution requirements

If rejected:

Send polite rejection (if policy allows)
Provide reason (if appropriate)
Note reconsideration conditions (if applicable)

Pre-registration checklist:

✅ Identity verified with government ID
✅ Contact information confirmed (phone/email work)
✅ Committee vote recorded (majority approval)
✅ No outstanding debts to organization from past membership
✅ Approval documented in committee minutes

Stage 3: System Registration

Who: Administrator with organization_users:write permission

Create Organization User

API Endpoint: POST /organization-users Request:

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)	New user details
`newUser.name`	string	Yes	Full legal name
`newUser.phone`	string	Yes	Rwandan phone (+250…)
`newUser.email`	string	No	Email address
`userId`	string	No	Existing user ID (if user already exists)
`joinDate`	string	Yes	Join date (ISO format)
`sendInvitation`	boolean	No	Send invitation email/SMS? (default: true)

What happens:

User account created (if newUser provided):
- System checks if email/phone already exists
- If exists: Links to existing user
- If new: Creates user account
Organization user created:
- Links user to organization
- Sets join date
- Status set to active
- No roles assigned yet (must assign separately)
Invitation sent (if sendInvitation=true):
- Email sent (if user has email): Secure link to set password
- SMS sent (if user has phone and no email): Link to set password
- Manual only (if no email/phone): Administrator must provide credentials manually
- Expiration: Invitation link valid for 72 hours

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://agatabo.com/invite?token=xyz...",
      "expiresAt": "2026-06-04T00:00:00.000Z",
      "deliveryMode": "sent",
      "channel": "EMAIL"
    }
  }
}

Invitation delivery modes:

"sent" - Email or SMS sent successfully
"manual_only" - No email/phone available, must share link manually

What Member Receives

If email provided: Subject: “You’ve been invited to [Organization Name]” Body:

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.

If you didn't request this, please ignore this email.

If phone only (no email): SMS:

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

Member activation:

Member clicks link
Member sets password (minimum 6 characters)
Account activated
Member can log in immediately

Stage 4: Role Assignment

Who: Administrator with organization_user_roles:assign permission CRITICAL: Organization user must have “member” role assigned to:

Record deposits for the member
Issue loans to the member
Track savings and contributions
Generate account statements

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

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

What happens when “member” role assigned:

Savings ledger account automatically created:
- Role: SAVINGS (liability account)
- Linked to organization user
- Balance starts at 0
- Required for recording deposits
Organization user becomes loan-eligible:
- Can now apply for loans
- Can record deposits
- Can record withdrawals
Member can track finances:
- View savings balance
- View loan status
- View account statement

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",
  "updatedAt": "2026-06-13T10:30:00.000Z"
}

Verify savings account created: After role assignment, check that savings ledger account was created:

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

Response should include:

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

Stage 5: Financial Setup

Who: Treasurer with savings:write permission Collect initial contribution (if required by organization policy): Common initial contributions:

Membership fee: One-time joining fee (e.g., 5,000 RWF)
Initial savings deposit: Minimum opening balance (e.g., 10,000 RWF)
Share capital: Ownership stake (e.g., 20,000 RWF)

Record Initial Deposit

API Endpoint: POST /savings Request:

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 fee + 10K savings + 20K shares"
}

What happens:

Deposit recorded:
- Member’s savings account credited: 35,000 RWF
- Cash/bank account debited: 35,000 RWF
- Journal entry created
Receipt generated:
- Available via API
- Print and give to member
- File copy in member’s folder

Member can now:

View savings balance
Apply for loans (if eligible based on savings)
Make additional deposits

Record Entry Fee (Optional)

If organization tracks entry fees separately: API Endpoint: POST /organization-users/{organizationUserId}/entry-fee Request:

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": "Membership entry fee"
}

Note: Entry fee requires organization user to have “member” role assigned.

Stage 6: Member Orientation

Who: Board Member, Treasurer, or Training Coordinator Conduct orientation session (1-2 hours):

Explain organization operations

Financial operations:

Contribution schedule (amount, frequency, due dates)
Payment methods (cash, mobile money, bank transfer)
Late payment penalties
Savings withdrawal rules

Loans:

Eligibility requirements (minimum savings, no delinquent loans)
Application process
Interest rates and calculation methods
Repayment terms and penalties for default
Guarantor/collateral requirements

Dividends:

How dividends are calculated
Distribution frequency
Eligibility requirements
Tax implications (if applicable)

Demonstrate Agatabo system

Member portal walkthrough:

How to log in (email/phone + password)
How to view savings balance
How to view transaction history
How to check loan eligibility
How to apply for loan (if self-service enabled)
How to view loan repayment schedule
How to update profile information
How to reset password

Review bylaws and policies

Governance:

Member rights and responsibilities
Voting procedures
Meeting attendance requirements
Committee structure

Policies:

Withdrawal/exit procedures
Refund of shares/savings upon exit
Confidentiality and privacy rules
Dispute resolution process

Provide materials

Printed or digital copy of bylaws
Contribution schedule
Loan application form (if paper-based process)
Treasurer/administrator contact information
Agatabo login instructions
Emergency contact numbers

Orientation checklist:

✅ Member understands contribution requirements
✅ Member knows loan eligibility rules
✅ Member can log in to Agatabo successfully
✅ Member signed membership agreement
✅ Member received copy of bylaws
✅ Member knows who to contact for help

Stage 7: Activation & Monitoring

Who: Treasurer, Membership Coordinator

Immediate Actions

Add to contribution tracking

Note member’s contribution schedule
Set reminder for first contribution due date
Add to SMS/email reminder list
Document expected contribution frequency

Create member file

Physical or digital folder containing:

Membership application form
Copy of government ID
Signed bylaws acknowledgment
Initial deposit receipt
Orientation attendance record
Committee approval minutes
Signed loan/guarantee agreements (when applicable)

Update member register

Add to official member list
Update total member count
Note join date for anniversary tracking
Record assigned member number (if used)

Announce new member

If organization policy requires:

Announce at next member meeting
Send welcome message to all members
Introduce new member to key personnel

First 3 Months Monitoring

Track engagement:

✅ Contribution consistency (making regular deposits?)
✅ Meeting attendance (participating in governance?)
✅ System usage (logging in, checking balance?)
✅ Questions/concerns raised?

Proactive follow-up:

Follow up immediately on missed contributions
Call member 1 week after joining to check in
Offer support/reminders as needed
Answer questions promptly
Pair with experienced “buddy” member

Early warning signs:

Missed first contribution (immediate follow-up needed)
Never logged into Agatabo (may need technical support)
Not attending meetings (engagement issue?)
Multiple questions about withdrawal (may not be committed)

Complete Onboarding Checklist

Pre-Registration

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

System Registration

✅ Organization user created in Agatabo
✅ Invitation sent (email/SMS or manual link shared)
✅ Member confirmed account activation
✅ Member can log in successfully
✅ “Member” role assigned (CRITICAL - required for all financial operations)
✅ Savings ledger account automatically created (verify with GET /organization-users/)

Financial Setup

✅ Initial contribution collected (cash received)
✅ Deposit recorded in Agatabo (POST /savings)
✅ Receipt issued to member (printed or digital)
✅ Member savings balance shows correctly in system

Orientation

✅ Orientation session completed (1-2 hours)
✅ Bylaws provided and explained
✅ Agatabo system demonstrated (member can navigate)
✅ Contribution schedule provided (member knows due dates)
✅ Membership agreement signed

Activation

✅ Member file created and organized (physical/digital folder)
✅ Member added to contribution reminders (email/SMS list)
✅ Official member register updated (total count incremented)
✅ Welcome announcement made (if required)
✅ First contribution due date scheduled

Timeline Example

Day	Activity
Day 1	Candidate submits application with required documents
Day 3-5	Verification of identity, phone, email, references
Day 7	Committee meeting - membership approval vote
Day 8	Create organization user in Agatabo, send invitation
Day 9	Member receives email/SMS, sets password, activates account
Day 9	Assign “member” role (triggers savings account creation)
Day 10	Collect initial contribution, record deposit in system
Day 11	Orientation session (1-2 hours) - explain operations, demo Agatabo
Day 12	Member fully active - first regular contribution due [scheduled date]

Total time: 10-14 days from application to full activation

API Workflow Summary

Complete API sequence for onboarding:

# 1. Create organization user
POST /organization-users
{
  "newUser": { "name": "Jane", "phone": "+250...", "email": "..." },
  "joinDate": "2026-06-01",
  "sendInvitation": true
}

# 2. Member activates account via invitation link (sets password)

# 3. Assign "member" role (triggers savings account creation)
POST /organization-users/{organizationUserId}/role-assignments
{
  "roleDefinitionId": "{member-role-id}",
  "assignedAt": "2026-06-01"
}

# 4. Verify savings account created
GET /organization-users/{organizationUserId}
# Check response: savingsLedgerAccountId should be set

# 5. Record initial deposit
POST /savings
{
  "organizationUserId": "{organizationUserId}",
  "amount": 35000,
  "transactionDate": "2026-06-01",
  "paymentMethod": "CASH",
  "description": "Initial membership deposit"
}

# 6. (Optional) Record entry fee separately
POST /organization-users/{organizationUserId}/entry-fee
{
  "amount": 5000,
  "transactionDate": "2026-06-01",
  "paymentMethod": "CASH"
}

Common Issues

Member invitation email not received

Possible causes:

Email address entered incorrectly
Email went to spam/junk folder
Invitation expired (72 hours)
Email service not configured

Solutions:

Resend invitation: GET /organization-users/me/pending-invitation-link
Check spam folder: Ask member to check junk/spam
Manual credentials: Create account with temporary password, provide in person
Use phone only: If no email, member can log in with phone number

Cannot record deposit for new member

Error: “Savings can only be recorded for organization users with member role”Cause: “member” role not assigned yetSolution:

Assign “member” role: POST /organization-users//role-assignments
Verify savings account created: GET /organization-users/ (check savingsLedgerAccountId)
Then record deposit: POST /savings

Member joins mid-month - how to handle contributions?

Options:Option 1: Full contribution immediately (recommended):

Member pays full monthly amount on join date
Simplest for bookkeeping
Member’s contribution schedule aligns with calendar month

Option 2: Pro-rate first contribution:

Calculate: (days remaining / total days) × monthly amount
Example: Join June 15, monthly = 10,000 RWF
Pro-rated: (15 days / 30 days) × 10,000 = 5,000 RWF
Next month: Full 10,000 RWF

Option 3: Skip first month:

Member starts contributing next month
Simpler but delays building savings

Recommendation: Option 1 (full contribution) for clarity and consistency.

Member doesn't have required initial deposit

Options:Option 1: Delay activation:

Member remains inactive until deposit collected
Clear expectation, no exceptions

Option 2: Installment plan:

Allow partial payment (e.g., 50% now, 50% next month)
Document agreement
Activate after first installment

Option 3: Waive requirement:

Committee can waive initial deposit
Must be documented in minutes
Apply consistently to avoid favoritism

Recommendation: Option 1 (delay activation) to maintain standards. Option 2 acceptable with clear documentation.

Savings account not created after role assignment

Expected behavior: Savings account automatically created when “member” role assignedIf not created:

Verify role assignment succeeded: GET /organization-users//role-assignments
Check if correct role: Must be role with key=“member”
Check organizationUser record: GET /organization-users/, verify savingsLedgerAccountId is set
Manual creation (if needed): Contact system administrator

Prevention: Always verify savings account created after assigning member role.

Member wants to join but lives far away

Considerations:

Can member attend meetings regularly? (quarterly minimum recommended)
How will member make contributions? (mobile money, bank transfer?)
How will member access loans? (require in-person for large amounts?)
Will member participate in governance? (voting, committees?)
Is there a more local tontine better suited?

Recommendation:

Approve only if member can participate effectively remotely
Require video call orientation if in-person not possible
Set up mobile money for contributions
Document remote participation policies

Best Practices

Successful onboarding strategies:Process efficiency:

✅ Complete onboarding within 2 weeks of application
✅ Use standardized checklist (don’t miss steps)
✅ Schedule orientation sessions regularly (don’t wait for individuals)
✅ Automate reminders for new member follow-ups

Member engagement:

✅ Buddy system: Pair new member with experienced member for first 3 months
✅ Immediate involvement: Invite to next meeting (within 2 weeks of joining)
✅ Personal touch: Call member 1 week after joining to check in
✅ Celebrate milestones: Acknowledge first contribution, first loan, 1-year anniversary

Documentation:

✅ Keep complete records (application, ID, agreements)
✅ Document committee approvals in minutes
✅ File receipts for all payments
✅ Maintain digital backups of member files

Quality control:

✅ Track conversion rate: How many applicants become active members?
✅ Monitor dropouts: Where do new members drop off? (before deposit? after first month?)
✅ Review process quarterly: What’s working? What’s confusing?
✅ Standardize orientation: Same information for all members

System usage:

✅ Verify member can log in during orientation
✅ Show member how to check their balance
✅ Provide written login instructions
✅ Offer technical support for login issues

Inviting Members

Detailed API documentation for member invitation

Recording Deposits

How to record initial contribution

Managing Roles

Role assignment and permissions

Account Statements

View member transaction history

​Overview

​Workflow Stages

​Stage 1: Recruitment & Application

​Stage 2: Verification & Approval

​Stage 3: System Registration

​Create Organization User

​What Member Receives

​Stage 4: Role Assignment

​Stage 5: Financial Setup

​Record Initial Deposit

​Record Entry Fee (Optional)

​Stage 6: Member Orientation

​Stage 7: Activation & Monitoring

​Immediate Actions

​First 3 Months Monitoring

​Complete Onboarding Checklist

​Pre-Registration

​System Registration

​Financial Setup

​Orientation

​Activation

​Timeline Example

​API Workflow Summary

​Common Issues

​Best Practices

​Related Topics

Inviting Members

Recording Deposits

Managing Roles

Account Statements

Overview

Workflow Stages

Stage 1: Recruitment & Application

Stage 2: Verification & Approval

Stage 3: System Registration

Create Organization User

What Member Receives

Stage 4: Role Assignment

Stage 5: Financial Setup

Record Initial Deposit

Record Entry Fee (Optional)

Stage 6: Member Orientation

Stage 7: Activation & Monitoring

Immediate Actions

First 3 Months Monitoring

Complete Onboarding Checklist

Pre-Registration

System Registration

Financial Setup

Orientation

Activation

Timeline Example

API Workflow Summary

Common Issues

Best Practices

Related Topics