Partner Organization Signup System

Overview

The Partner Organization Signup System allows organizations to create custom signup flows that function as white-label versions of the main business valuation calculator. These flows automatically create business profiles from collected valuation data.

Key Features

1. White-Label Valuation Calculator

• Organizations can brand their signup experience
• Custom flows collect full business valuation data
• Seamless integration with the main platform

2. Automatic Profile Creation

• Immediate Creation: If the user already exists in the system, their business profile is created immediately upon approval
• Deferred Creation: If the user doesn’t exist yet, profile data is saved and the profile is created automatically when they first log in
• Auto-Approval: Organizations can configure flows to auto-approve submissions and create profiles instantly

3. Valuation Components

The system includes specialized components for collecting valuation data: - Business Type Selector: Industry classification with valuation multiples - Location Management: Multiple business locations with geocoding - Financial Data Entry: Multi-year revenue, cash flow, and net income - Risk Assessment: Business risk factors that affect valuation - Comparable Selection: Find and select similar businesses for market-based valuation

Architecture

Frontend Components

SignupFlowEditor

Located at: alphabiz-ui/src/components/organization/SignupFlowEditor.tsx - Drag-and-drop interface for building signup flows - Valuation field library with pre-built components - Template selection (includes “Business Valuation Flow”) - Real-time preview

Component Adapters

Located at: alphabiz-ui/src/components/questionnaire/adapters/ - BusinessTypeAdapter: Wraps MultipleForm component - LocationAdapter: Manages multiple business locations - YearFormAdapter: Financial data with year management - RiskFactorsAdapter: Risk assessment interface - CompsAdapter: Comparable business selection with map

SignupFlowManager

Located at: alphabiz-ui/src/components/organization/SignupFlowManager.tsx - Manage organization signup flows - View and process submissions - Approval interface with profile creation status

Backend Integration

Profile Creation Flow

1. User submits signup form with valuation data
2. Organization admin reviews submission
3. Upon approval:
   • If user exists → Profile created immediately
   • If user doesn’t exist → Data saved for later creation
4. When new user logs in → Profile created from saved data

Data Mapping

# Questionnaire fields → Profile structure
business_type → multipleForm.businessTypeId
business_description → multipleForm.businessDescription
locations → locations array with place data
financials → allYears (Map converted to object)
risk_factors → multipleForm.flags
comparables → comps array
asking_price → askingPrice

Key Files

• valuation_api/api_routes/organization_signup_routes.py: Main signup API endpoints
• valuation_api/api_route.py: Login hook for deferred profile creation
• valuation_api/models/uuid_models.py: Database models

API Reference

Public Endpoints

Get Organization Signup Flow

GET /api/signup/{org_code}

Returns the active signup flow configuration for an organization.

Submit Signup

POST /api/signup/{org_code}/submit
Content-Type: application/json

{
  "email": "user@example.com",
  "business_name": "My Business",
  "business_type": {
    "businessTypeId": "uuid",
    "businessDescription": "Description"
  },
  "locations": [...],
  "financials": {...},
  "risk_factors": {...},
  "comparables": [...]
}

Admin Endpoints

List Signup Flows

GET /api/partner-org/{org_id}/signup-flows
Authorization: Bearer {token}

Create Signup Flow

POST /api/partner-org/{org_id}/signup-flows
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Business Valuation Signup",
  "description": "Complete valuation during signup",
  "flow_config": {...},
  "is_active": true
}

List Submissions

GET /api/partner-org/{org_id}/signup-submissions?status=PENDING
Authorization: Bearer {token}

Approve Submission

POST /api/partner-org/{org_id}/signup-submissions/{submission_id}/approve
Authorization: Bearer {token}
Content-Type: application/json

{
  "role": "member",
  "notes": "Approved with complete valuation data"
}

Response:

{
  "status": "approved",
  "user_added": true,
  "profile_created": true,
  "profile_data_saved": false,
  "message": null
}

Configuration

Auto-Approval Settings

{
  "signup_settings": {
    "auto_approve": true,
    "default_role": "member",
    "require_email_verification": false
  }
}

Default Valuation Flow Template

import { defaultValuationFlow } from '@/components/organization/defaultValuationFlow';

// 7-step flow with all valuation components
const flow = {
  ...defaultValuationFlow,
  name: "Custom Business Valuation",
  settings: {
    auto_approve: true
  }
};

Best Practices

1. Data Quality

• Make key fields required (business type, at least one year of financials)
• Add validation rules for financial data
• Use conditional logic to show relevant fields

2. User Experience

• Provide clear instructions for each step
• Use the template as a starting point
• Test the complete flow before activating

3. Profile Management

• Monitor submission approvals
• Check that profiles are created correctly
• Review profile data quality

4. Security

• Enable email verification for sensitive industries
• Review submissions before approval
• Set appropriate default roles

Troubleshooting

Profile Not Created

1. Check if submission contains valuation data
2. Verify user approval status
3. Check login hook logs for deferred creation
4. Ensure profile creation function has no errors

Missing Data in Profile

1. Verify field mappings in submission
2. Check data transformation logic
3. Review questionnaire configuration
4. Test with complete data set

Auto-Approval Not Working

1. Verify organization signup settings
2. Check flow is marked as active
3. Review error logs for failures
4. Test with manual approval first

Example Implementation

// 1. Create organization
const org = await createOrganization({
  name: "Tech Accelerator",
  code: "tech-accel"
});

// 2. Enable signup
await updateSignupSettings(org.id, {
  signup_enabled: true,
  signup_settings: {
    auto_approve: false,
    default_role: "member"
  }
});

// 3. Create valuation flow
const flow = await createSignupFlow(org.id, {
  name: "Tech Startup Valuation",
  flow_config: defaultValuationFlow,
  is_active: true
});

// 4. Share signup URL
const signupUrl = `https://app.example.com/signup/tech-accel`;

// 5. Process submissions
const submissions = await getSubmissions(org.id, "PENDING");
for (const sub of submissions) {
  if (hasValuationData(sub)) {
    await approveSubmission(org.id, sub.id);
    // Profile created automatically!
  }
}

Future Enhancements

1. Bulk Import: Allow organizations to import existing member data
2. Custom Workflows: Post-approval automation and notifications
3. Analytics: Track conversion rates and profile quality
4. Templates: Industry-specific valuation flow templates
5. Integration: Connect with CRM and accounting systems