Introduction

Salesman is a comprehensive sales operations platform designed to manage the complete lifecycle of sales leads, from creation through approval and payout. It serves multiple user roles across organizations:

1. Lead Management – Track sales opportunities from initial contact through contract signing and approval
2. Agent Coordination – Manage sales agents, assign leads, and track individual performance
3. Commission & Payout Management – Calculate and process commissions based on configurable policies, including agent commissions, manager overrides, and customer referrals
4. Customer Portal – Allow customers to view available products, track their purchase status, and submit referrals
5. Operations & Task Management – Create and track jobs spawned from approved leads with customizable statuses and workflows
6. E-Signature Integration – Integrate with OpenSign for multi-stage contract signing workflows

Features

• Multi-tenant architecture: Each organization operates independently with isolated leads, agents, customers, and configurations
• Configurable commission policies: Define complex commission structures with fixed/percentage-based commissions, manager overrides, and referral bonuses
• Multi-stage signing workflows: Design custom contract signing stages with templated documents and automated OpenSign integration
• Customizable job templates: Create default operational tasks that spawn automatically when leads are approved
• SMTP email customization: Each organization can configure its own email server and customize transactional email templates
• Grant & discount system: Create fixed or percentage-based discounts applicable to products
• Product marketplace: Customers can browse available products and express interest, creating leads automatically
• Referral system: Customers can refer others and earn commissions when referral leads are approved
• Role-based access control: Five user roles (SUPER_ROOT, ROOT, ADMIN, AGENT, OPERATIONS) with role-specific permissions and UI

Concepts

Organisation

An organisation represents a business tenant on the platform. Each organization manages its own:

• Sales leads and customer relationships
• Sales agents and team members
• Products with configurable commission policies and multi-stage signing workflows
• Email settings (SMTP server and custom templates)
• Projects and operational job templates
• Grants (discounts) and custom job status configurations

Organizations are completely isolated from each other, ensuring data privacy and security. A single ROOT user owns the organization and has full administrative privileges.

User Roles

SUPER_ROOT (Platform Administrator)

A platform-wide super-administrator who can:

• View and manage all organizations on the platform
• Create new organizations
• Configure global default email templates for all organizations
• Manage platform-wide users

ROOT (Organization Owner)

The primary administrator of an organization who can:

• View and update organization details (name, contact information, etc.)
• Configure organization settings:
  • SMTP email server and credentials
  • Organization-specific email templates (override global defaults)
  • Projects and allowed users per project
  • Job status configurations
• Invite ADMIN users to the organization
• View all leads within the organization (full visibility)
• Approve or reject leads (controlling financial and operational decisions)
• Initiate payouts to agents and referrers

ADMIN (Operations Administrator)

An administrative user within an organization who can:

• Manage team: Invite and manage agents and customers
• Manage sales: View all leads, assign leads to agents, transition leads through various statuses
• Manage products: Create/edit products with commission policies, sign stages, and job templates
• Manage operations: Create grants/discounts, manage job templates, assign jobs, record customer payments
• Manage payouts: View payout units and acknowledge received payouts
• Manage documents: Upload and review documents across the organization

AGENT (Sales Agent)

A sales professional who can:

• Work on leads: View only their own leads plus unassigned NEW leads (shared pool)
• Create leads: Add new sales opportunities to the system
• Progress deals: Transition their leads through statuses (NEW → CONTACTED → NEGOTIATION → SIGNING)
• Send contracts: Trigger multi-stage signing requests via OpenSign
• Manage communications: Upload documents and invite customers to the portal
• Track earnings: View their own payout units and payouts

OPERATIONS (Operations User)

An operational coordinator who can:

• Coordinate tasks: View all leads and customers; manage jobs with status transitions
• Support sales: Record customer payments, upload documents
• Full visibility: See all operational data for task coordination

CUSTOMER (Portal User)

A customer/buyer who can:

• Browse marketplace: View available products from the organization
• Track purchases: Monitor the status of their leads/contracts (NEW → SIGNED → APPROVED → CLOSED)
• Express interest: Create leads by indicating interest in a product
• Submit referrals: Refer other customers (if the product supports referral commissions)
• View payouts: Track referral commission payments
• Sign documents: Review and sign contracts via OpenSign e-signature workflow

Product

A product represents a sellable item managed by the organization. Each product can have:

• Commission policy: Defines payouts structure:
  • Agent commissions (COMMISSION type): What the selling agent earns
  • Manager overrides (OVERRIDE type): What managers earn on agent sales
  • Referral bonuses (REFERRAL type): What customer referrers earn
• Signing stages: Multi-stage contract workflow, each with:
  • OpenSign template ID
  • Custom widget mapping (e.g., customer name, product name)
  • Display order
• Job templates: Operational tasks that auto-spawn when leads are approved (e.g., Setup, Training, Application Submission, Claim Submission, Customer Reimbursement)
• Availability status: Control visibility in the customer portal marketplace

Lead

A lead represents a single sales opportunity—one customer's interest in one product. A lead lifecycle progresses through statuses:

• NEW: Created, waiting for agent contact (unassigned leads form a shared pool)
• CONTACTED: Agent has reached out to the customer
• NEGOTIATION: Active discussions between agent and customer
• SIGNING: Contract signing stage is active (OpenSign document sent)
• AWAITING_APPROVAL: All documents signed, pending admin/ROOT review
• APPROVED: Approved by admin/ROOT; payout units and operational jobs are created
• REJECTED: Rejected by admin/ROOT; no payouts or jobs created
• CLOSED: Final state (reachable from various states)

A lead contains:

• Customer: The buyer (may not have a portal account)
• Product: The item being sold
• Agent: The assigned sales representative
• Referrer: Optional; if this is a referral lead, points to the referring customer
• Signing stages: Progress through multi-stage contract signing (index tracks current stage)
• Payment status: Whether the customer has paid (recorded by admin/operations)
• Commission policy enforcement: Used to calculate payout units

Payout Unit

A payout unit represents one earning line item for a sales agent, manager, or customer referrer. Created automatically when a lead is approved based on the product's commission policy. Each payout unit has:

• Type: COMMISSION (agent), OVERRIDE (manager), or REFERRAL (customer referrer)
• Status: PENDING or PAID
• Amount: Calculated from the commission policy
• Lead: The lead that generated this earning
• Agent: Who is receiving payment (even for REFERRAL type)
• Referrer (for REFERRAL type only): The customer who referred

Multiple payout units from different leads can be grouped into a single Payout for batch disbursement.

Job & Job Template

Operational tasks created automatically when a lead is approved. The organization defines default job templates per product (Setup, Training, Application Submission, etc.), and when a lead is approved, a Job is created for each template.

Each job has:

• Status: Tracked via customizable JobStatusConfig (colors, display order, terminal states)
• Assigned user: An agent or operations user responsible for completion
• History: Complete audit trail of all status transitions

Organizations can customize job statuses (e.g., add "Pending Review", "In Progress", "Completed") to match their workflows.

Grant (Discount)

A discount or incentive that can be applied to products and attached to leads. Grants can be:

• Fixed: A specific amount (e.g., SGD 100 off)
• Percentage: A percentage discount (e.g., 10% off)

Grants are useful for promotions, loyalty programs, or negotiation incentives.

Email Customization

Each organization can:

• Configure SMTP server: Hostname, port, credentials, sender identity
• Customize templates: Override global defaults for transactional emails:
  • Password reset
  • User invite
  • Contract signing request
  • Payout received
  • Payment received
  • Lead status change
  • Signing approval/rejection

If an organization doesn't set a custom template, the global default (from platform settings) is used.

Project

An organizational unit for grouping operational work. Each organization has at least a default "General Operations" project. Projects can:

• Restrict user access: Specify which users (agents) can access this project
• Group job templates: Organize job templates by project
• Enable scoped work: Allow matrix management where agents work across projects

Job Status Config

Customizable status labels for jobs within an organization. Each organization can define statuses like "Pending", "In Progress", "Review", "Completed", etc. Statuses include:

• Name & slug: Display label and URL-safe identifier
• Color: Hex colour for UI distinction
• Sort order: Display order in UI
• Is default: Applied to newly created jobs
• Is terminal: Marks completion states (jobs stop progressing after reaching terminal state)
• Is active: Soft-delete flag for archival

Workflow Overview

Organization Setup

1. A SUPER_ROOT administrator creates a new organization for a business
2. A ROOT user is assigned to manage the organization
3. ROOT user configures:
   • Organization details (name, contact information)
   • SMTP email server for outbound communications
   • Email templates (customized or using platform defaults)
   • Products with pricing, commission policies, and signing stage templates
   • Job templates and status configurations
   • Projects and user permissions
4. ROOT user invites ADMIN users to the organization

Lead Lifecycle

1. Lead Creation

• Admin creates leads manually OR Agents create their own leads OR Customers express interest via the portal marketplace
• System prevents duplicate leads for the same customer+product combination
• Initial status: NEW, unassigned (agents see it in their shared pool)

2. Lead Assignment

• Admin assigns unassigned NEW leads to specific agents
• Agents can also claim unassigned leads from the shared pool

3. Initial Contact

• Agent transitions lead: NEW → CONTACTED
• Agent reaches out to customer and begins conversations

4. Negotiation

• Agent transitions lead: CONTACTED → NEGOTIATION
• Agent discusses terms, pricing, and customizations with customer
• Agents can upload supporting documents (quotes, proposals, etc.)

5. Contract Signing (Multi-Stage)

• Agent (or admin) triggers signature request: lead transitions to SIGNING
• System sends first OpenSign document for the first signing stage
• Customer (or authorized signatory) receives e-signature request
• OpenSign webhook events flow:
  • created → Signature request created
  • viewed → Customer opens document
  • signed → Customer provides signature
  • completed → All required signings finished for this stage
    • If more stages exist: Lead returns to NEGOTIATION, next stage begins
    • If all stages complete: Lead transitions to AWAITING_APPROVAL
  • declined → Customer rejects contract; lead moves to REJECTED

6. Admin Review & Approval

• ROOT or ADMIN user reviews the deal in AWAITING_APPROVAL status
• Can view all documents, customer information, and agent notes
• Approves (→ APPROVED) or Rejects (→ REJECTED) the lead

7. Post-Approval Automation

When a lead is approved, the system automatically:

• Creates payout units based on the product's commission policy:
  • Agent commission (COMMISSION type)
  • Manager override (OVERRIDE type, if applicable)
  • Customer referral bonus (REFERRAL type, if this was a referred lead)
• Creates operational jobs from the product's default job templates (Setup, Training, Application Submission, etc.)
• Sends notifications to relevant stakeholders

8. Lead Closure

• After approval, agents and admin can transition the lead to CLOSED at any time
• Operational jobs continue until marked complete with terminal statuses

Payout Processing

1. Payout Unit Accumulation

• As leads are approved, agents accumulate payout units
• Each payout unit represents one earning line (commission, override, or referral)
• Agents can view their pending payout units on the Payout Units page

2. Bulk Payout Initiation

• Admin or ROOT selects multiple pending payout units
• Optionally attaches a proof document (payment confirmation, transfer receipt, etc.)
• Creates a Payout record grouping the units together
• Sends "Payout Received" email to each earner
• Marks all included payout units as PAID

3. Payout Acknowledgement

• Agents and Referrer Customers can acknowledge receipt of the payout
• Provides an audit trail of acknowledgement

Customer Portal Experience

1. Account Invitation

• Admin invites a customer to the portal
• Customer receives invite email with temporary password
• Customer sets their permanent password on first login

2. Marketplace Browsing

• Customer views all available products (marked isAvailable=true)
• Each product shows:
  • Name, description, price
  • Organization name
  • Customer's current status with this product (if any)

3. Express Interest

• Customer clicks "Interested" on a product
• System creates a NEW unassigned lead automatically
• Prevents duplicate submissions (can't express interest twice for the same product)

4. Referral Submission

• Customer can refer another person for a product (if product has referral commission)
• System creates a NEW lead with the customer as the referrer
• If the referral lead is approved, the referrer earns a REFERRAL payout unit

5. Contract Tracking

• Customer can view all their leads/contracts in the "My Contracts" section
• Shows status, signing stage progress, and history
• Can review and download signed documents

6. Referral History & Payouts

• Customer can view all referrals they've submitted
• Can see referral payout history (earnings from successful referrals)