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

# New Member Onboarding

> Step-by-step process for registering new members

## Overview

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

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

***

## Workflow Stages

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

***

## Stage 1: Recruitment & Application

**Who**: Existing members or Recruitment Committee

**Activities**:

<Steps>
  <Step title="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
  </Step>

  <Step title="Candidate expresses interest">
    * Provides basic contact information
    * Attends informational meeting
    * Receives application materials
  </Step>

  <Step title="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)
  </Step>
</Steps>

**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**:

<Steps>
  <Step title="Verify candidate information">
    * Confirm identity (check government ID)
    * Verify phone number (test call/SMS)
    * Verify email address (if provided)
    * Check references (if policy requires)
  </Step>

  <Step title="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?
  </Step>

  <Step title="Committee review">
    * Present candidate to membership committee
    * Vote on membership approval
    * Document approval decision in meeting minutes
  </Step>

  <Step title="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)
  </Step>
</Steps>

**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**:

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

1. **User account created** (if newUser provided):
   * System checks if email/phone already exists
   * If exists: Links to existing user
   * If new: Creates user account

2. **Organization user created**:
   * Links user to organization
   * Sets join date
   * Status set to active
   * **No roles assigned yet** (must assign separately)

3. **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)**:

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

1. Member clicks link
2. Member sets password (minimum 6 characters)
3. Account activated
4. 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**:

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

1. **Savings ledger account automatically created**:
   * Role: `SAVINGS` (liability account)
   * Linked to organization user
   * Balance starts at 0
   * Required for recording deposits

2. **Organization user becomes loan-eligible**:
   * Can now apply for loans
   * Can record deposits
   * Can record withdrawals

3. **Member can track finances**:
   * View savings balance
   * View loan status
   * View account statement

**Response (201 Created)**:

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

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

Response should include:

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

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

1. **Deposit recorded**:
   * Member's savings account credited: 35,000 RWF
   * Cash/bank account debited: 35,000 RWF
   * Journal entry created

2. **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**:

```http theme={null}
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):

<Steps>
  <Step title="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)
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>

  <Step title="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
  </Step>
</Steps>

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

<Steps>
  <Step title="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
  </Step>

  <Step title="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)
  </Step>

  <Step title="Update member register">
    * Add to official member list
    * Update total member count
    * Note join date for anniversary tracking
    * Record assigned member number (if used)
  </Step>

  <Step title="Announce new member">
    **If organization policy requires**:

    * Announce at next member meeting
    * Send welcome message to all members
    * Introduce new member to key personnel
  </Step>
</Steps>

***

### 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/{id})

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

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

<AccordionGroup>
  <Accordion title="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**:

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

  <Accordion title="Cannot record deposit for new member">
    **Error**: "Savings can only be recorded for organization users with member role"

    **Cause**: "member" role not assigned yet

    **Solution**:

    1. Assign "member" role: POST /organization-users/{id}/role-assignments
    2. Verify savings account created: GET /organization-users/{id} (check savingsLedgerAccountId)
    3. Then record deposit: POST /savings
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Savings account not created after role assignment">
    **Expected behavior**: Savings account automatically created when "member" role assigned

    **If not created**:

    1. **Verify role assignment succeeded**: GET /organization-users/{id}/role-assignments
    2. **Check if correct role**: Must be role with key="member"
    3. **Check organizationUser record**: GET /organization-users/{id}, verify savingsLedgerAccountId is set
    4. **Manual creation** (if needed): Contact system administrator

    **Prevention**: Always verify savings account created after assigning member role.
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

***

## Best Practices

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

***

## Related Topics

<CardGroup cols={2}>
  <Card title="Inviting Members" icon="user-plus" href="/tontines/organization-users/inviting-users">
    Detailed API documentation for member invitation
  </Card>

  <Card title="Recording Deposits" icon="money-bill-wave" href="/tontines/deposits-savings/recording-deposits">
    How to record initial contribution
  </Card>

  <Card title="Managing Roles" icon="user-tag" href="/tontines/organization-users/roles">
    Role assignment and permissions
  </Card>

  <Card title="Account Statements" icon="file-invoice" href="/tontines/reports/account-statements">
    View member transaction history
  </Card>
</CardGroup>