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

# Inviting Users

> Step-by-step guide to inviting new people to your tontine - members and staff

## Overview

Inviting users is the first step in onboarding new people to your tontine. When you invite someone, Agatabo creates their user profile and sends an invitation via email or SMS (depending on what's available and enabled).

**Use this when**: A new person needs access to the system - whether they're a member (who saves/borrows) or staff (who operates the system).

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `organization_users:write` permission (typically administrators only)
  * You have the person's basic information (name and phone required; email optional)
  * You understand roles are assigned AFTER user creation, not during
  * The person is not already in your organization
</Note>

<Note>
  **Member vs Organization User**: An "organization user" is anyone with login credentials and access to Agatabo. A "member" is an organization user with a member role who can have savings and loans. All members are organization users, but not all organization users are members.

  **Note**: Email is optional. Users can log in with either email or phone number.
</Note>

## Step-by-Step Instructions

### Step 1: Navigate to Organization Users

<Steps>
  <Step title="Open Organization Users section">
    Click **Organization Users** in the left sidebar
  </Step>

  <Step title="Click 'Add Organization User'">
    Opens the "Add New Organization User" dialog (usually top-right corner)
  </Step>
</Steps>

### Step 2: Enter User Information

The form contains the following fields:

| Field         | Description                               | Required | Example                                                 |
| ------------- | ----------------------------------------- | -------- | ------------------------------------------------------- |
| **Name**      | Full name (single field)                  | Yes      | John Mugisha                                            |
| **Join Date** | Date joined organization                  | Yes      | 2026-06-10                                              |
| **Phone**     | Mobile phone number with country code     | Yes      | +250788987654                                           |
| **Email**     | Email address for login and notifications | Optional | [john.mugisha@gmail.com](mailto:john.mugisha@gmail.com) |

<Note>
  **Email is optional**:

  * If email is provided, invitation is sent via email (requires email notifications enabled in settings)
  * If no email is provided, invitation is sent via SMS (requires SMS notifications enabled in settings)
  * If neither email nor SMS is enabled, you must copy the invitation link and share it manually
  * Users can log in with either email or phone number
</Note>

<Warning>
  **Important**: Name, Phone, and Email cannot be easily edited later. Verify information is correct before saving.
</Warning>

#### Example: Adding a New User

```
Name: Jane Uwase
Join Date: 2026-06-10
Phone: +250788123456
Email: jane.uwase@gmail.com  (optional)
```

### Step 3: Choose Invitation Option

Toggle whether to send an invitation immediately:

* **Send Invitation ON**: Invitation sent via email (if provided) or SMS (if enabled)
* **Send Invitation OFF**: User created but no invitation sent (you'll share the link manually)

<Note>
  **Manual invitation link**: Even with "Send Invitation ON", if neither email nor SMS notifications are configured, you'll receive a copyable invitation link to share manually with the user via WhatsApp, in person, or another method.
</Note>

### Step 4: Review and Submit

<Steps>
  <Step title="Review all information">
    Verify name, email, and phone are correct
  </Step>

  <Step title="Click 'Add Organization User'">
    Creates the user account
  </Step>

  <Step title="Confirm success">
    You'll see a confirmation message with the invitation status (sent via email, SMS, or link to copy)
  </Step>
</Steps>

## What Happens Next

When you create the user, Agatabo automatically:

1. **Creates the user profile**: Stores all user information in the database

2. **Generates activation token**: Creates a secure, one-time link for account setup

3. **Sends invitation** (depends on what's configured):

   * **If email provided + email notifications enabled**: Sends invitation email
   * **If no email + SMS notifications enabled**: Sends invitation via SMS
   * **If neither enabled**: Displays invitation link for you to copy and share manually

   The invitation contains:

   * Organization name
   * Activation link (expires in 72 hours)
   * Instructions for setting password

4. **Records in audit trail**: Logs the invitation with your user ID and timestamp

<Note>
  **Next step - Assign roles**: After creating the user, you need to assign roles. Navigate to the user's profile → Roles tab → Assign role (e.g., Member, Treasurer, Administrator).
</Note>

### Member's Experience

The invited person receives an invitation via email or SMS (or manually via link). The invitation contains an activation link that expires in 72 hours.

<Steps>
  <Step title="Member clicks activation link">
    Opens account setup page
  </Step>

  <Step title="Member sets password">
    Creates a secure password (minimum 8 characters)
  </Step>

  <Step title="Member logs in">
    Can log in using either their email or phone number
  </Step>
</Steps>

## Viewing Invited Members

After sending invitations, you can track their status:

<Steps>
  <Step title="Navigate to Organization Users">
    **Organization Users** section shows all users
  </Step>

  <Step title="Check invitation status">
    Users have status indicators:

    * **Pending**: Invitation sent, not yet activated
    * **Active**: Account activated, can log in
    * **Inactive**: Account deactivated
  </Step>

  <Step title="Resend invitation (if needed)">
    Click **Resend Invitation** for pending users
  </Step>
</Steps>

## Common Scenarios

### Inviting a Member Without Email

Email is optional. If the person doesn't have an email address:

<Steps>
  <Step title="Leave email field empty">
    Enter only name, join date, and phone number
  </Step>

  <Step title="Ensure SMS notifications are enabled">
    Go to Settings → Notifications and verify SMS is enabled
  </Step>

  <Step title="Send invitation">
    Invitation will be sent via SMS to their phone number
  </Step>

  <Step title="Member logs in with phone">
    They can use their phone number (instead of email) to log in
  </Step>
</Steps>

<Warning>
  **If SMS is not enabled**: You'll need to copy the invitation link and share it manually with the member.
</Warning>

### Enabling Notifications for Invitations

For invitations to be sent automatically:

<AccordionGroup>
  <Accordion title="Enable Email Notifications">
    1. Navigate to **Settings → General**
    2. Toggle **Enable Email** to ON
    3. Save changes
    4. Email invitations will now be sent automatically when email is provided
  </Accordion>

  <Accordion title="Enable SMS Notifications">
    1. Navigate to **Settings → General**
    2. Toggle **Enable SMS** to ON
    3. Save changes
    4. SMS invitations will now be sent when no email is provided
  </Accordion>

  <Accordion title="Manual Invitation (No Notifications Enabled)">
    If neither email nor SMS notifications are enabled:

    1. After creating the user, copy the invitation link displayed
    2. Share the link with the user via WhatsApp, in person, or another method
    3. User clicks the link to activate their account
    4. They can log in using their email or phone number
  </Accordion>
</AccordionGroup>

### Inviting Staff (Non-Members)

If inviting someone who works for the organization but doesn't save or borrow:

<Steps>
  <Step title="Enter their information">
    Same process as any user invitation (name, join date, phone, email)
  </Step>

  <Step title="Send invitation">
    Complete the invitation process to create the user account
  </Step>

  <Step title="Assign appropriate role">
    After user is created, navigate to their profile → Roles tab → Assign **Treasurer**, **Accountant**, or **Administrator** - but NOT "Member"
  </Step>
</Steps>

<Note>
  Staff without "Member" role cannot have savings accounts or take loans. They have operational access only.
</Note>

### Reinviting After Expiration

If the activation link expires (72 hours):

<Steps>
  <Step title="Find the user">
    **Organization Users** → Locate the pending user
  </Step>

  <Step title="Click 'Resend Invitation'">
    Generates a new activation link
  </Step>

  <Step title="New email sent">
    Member receives a fresh invitation email
  </Step>
</Steps>

## Common Issues

<AccordionGroup>
  <Accordion title="'User already exists in organization' error">
    **Cause**: This person (identified by email or phone number) already has an account in your organization.

    **Solution**:

    * Search Organization Users to find their existing account
    * If they were deactivated, reactivate their account instead of creating a new one
    * If this is genuinely a different person, they need a different email address and phone number
    * The system prevents duplicate accounts based on email/phone to maintain data integrity
  </Accordion>

  <Accordion title="'Insufficient permissions' error">
    **Cause**: Your user account doesn't have `organization_users:write` permission.

    **Solution**:

    * Contact your administrator to request user invitation permissions
    * Only administrators typically have this permission

    [Learn about permissions →](/reference/permissions-matrix)
  </Accordion>

  <Accordion title="Invitation email not received">
    **Possible causes**:

    * Email notifications are disabled in Settings → General
    * Email address is incorrect or has typos
    * Email is in spam/junk folder

    **Solution**:

    1. **Check Settings → General**: Verify "Enable Email" is toggled ON
    2. Verify the email address is correct (check for typos)
    3. Ask user to check spam/junk folder
    4. Resend invitation after fixing issues
    5. Add Agatabo sender email to contacts to prevent spam filtering

    **If email is disabled**: Copy the invitation link manually and share it with the user via WhatsApp or another method.
  </Accordion>

  <Accordion title="'Cannot assign role' error (after user creation)">
    **Cause**: You lack the `organization_user_roles:assign` permission, or you're trying to assign the Administrator role (which requires special handling).

    **Solution**:

    * **For permission issues**: Contact your administrator to grant you `organization_user_roles:assign` permission
    * **For Administrator role**: This role cannot be assigned through the normal Roles tab. Contact a system administrator to use the special admin assignment function.
    * **For other roles**: Ensure you have the `organization_user_roles:assign` permission

    **Note**: Role assignment is a separate operation from user creation and requires different permissions than inviting users.
  </Accordion>

  <Accordion title="Member cannot set password">
    **Cause**: Activation link expired, or link was already used.

    **Solution**:

    1. Resend invitation from **Organization Users** section
    2. Member uses the new activation link
    3. If problem persists, contact [support@agatabo.com](mailto:support@agatabo.com)
  </Accordion>
</AccordionGroup>

## Best Practices

<Note>
  **User invitation tips:**

  * Verify email address is correct before sending (typos prevent activation)
  * Include phone number with country code (+250 for Rwanda, etc.)
  * Use consistent naming format (First Last, or as preferred)
  * Send invitations in batches (10-20 at a time) to monitor activation
  * Follow up with users who don't activate within 3 days
  * Keep a record of invitation dates for tracking
  * After user creation, assign the minimum roles needed - you can always add more later
</Note>

## After Invitation

Once the member activates their account:

<CardGroup cols={2}>
  <Card title="Entry Fees" icon="coins" href="/tontines/organization-users/entry-fees">
    Record entry fees and initial contributions
  </Card>

  <Card title="Explain Features" icon="book-open" href="/tontines/getting-started/overview">
    Orient new members on how to use Agatabo
  </Card>

  <Card title="Generate Member Statement" icon="file-invoice" href="/tontines/reports/member-statements">
    Provide members with their account summary
  </Card>
</CardGroup>

## Related Operations

<CardGroup cols={2}>
  <Card title="Managing Users" icon="users-gear" href="/tontines/organization-users/managing-users">
    Edit member information, deactivate accounts, change roles
  </Card>

  <Card title="Member Roles Explained" icon="user-tag" href="/organization-users/roles">
    Understand different roles and their permissions
  </Card>

  <Card title="Viewing Member Details" icon="address-card" href="/organization-users/viewing-member-details">
    Access member profiles, savings, and loan history
  </Card>

  <Card title="New Member Workflow" icon="list-check" href="/workflows/new-member-onboarding">
    Complete checklist for onboarding new members
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Permissions Matrix" icon="shield-halved" href="/reference/permissions-matrix">
    Full reference of roles and their permissions
  </Card>

  <Card title="Understanding Roles" icon="sitemap" href="/organization-users/roles">
    Detailed explanation of each role type
  </Card>

  <Card title="User Management" icon="users" href="/organization-users/managing-users">
    Edit, deactivate, or modify user accounts
  </Card>

  <Card title="Common Errors" icon="triangle-exclamation" href="/troubleshooting/common-errors">
    Troubleshooting invitation issues
  </Card>
</CardGroup>