Skip to main content

Client Onboarding

Checklist and step-by-step guide for onboarding a new client onto the Client Portal platform.

Onboarding Checklist​

Use this as a sequential checklist. Each step depends on the previous.

1. Create Client Record​

Create the client organization in the clients table via the admin panel at /admin/clients.

Required fields:

  • Company name
  • Contact email (primary point of contact)
  • Contact name

Optional but recommended:

  • Company website
  • Logo URL
  • Availability settings (can be configured later)

2. Invite Users​

Invite the client's team members using the invite-user edge function or via the admin UI at /admin/users.

For each user:

  • Set role = 'client'
  • Set client_id to the newly created client
  • The invite sends a Supabase Auth email with a magic link or password setup

Verify the user can log in and sees their workspace at /workspace.

3. Define Markets​

Create markets for the client. Each market represents a tightly defined candidate segment.

Naming convention: [Specialization] --- [Scope] using an em dash.

  • Example: Patent Litigation --- Multi-Market
  • Example: M&A --- New York
  • Keep names under ~38 characters
  • Each name must be unique across the entire platform

Market definition includes:

  • Practice area (e.g., M&A, Litigation, IP, Patent)
  • Geography (e.g., NYC, Chicago, Texas, National)
  • Seniority range (e.g., Associate to Partner)
  • Optional firm tier filter (AmLaw 100, boutique, etc.)

4. Set Up Scheduling​

Guide the client through connecting their calendar for the built-in scheduling system:

  1. Client navigates to their account settings
  2. Clicks Connect Google Calendar or Connect Outlook Calendar
  3. Completes OAuth flow -- tokens stored in calendar_connections table
  4. Sets availability hours per day of the week
  5. Sets timezone

OAuth state format for client mode: {clientId}:{provider}

After connection, the client can create booking links from their workspace.

5. Create Campaigns​

Link campaigns to the client's markets. Each campaign:

  • Belongs to one client
  • Targets one or more markets
  • Has a type (validation sprint or ongoing coverage)
  • Optionally links to a GHL location via ghl_location_id

6. Configure Integrations (If Applicable)​

GoHighLevel (GHL):

  • Add a record to ghl_integrations with:
    • location_id -- The client's GHL location
    • api_token -- Bearer token for API access
    • custom_field_mapping -- JSON mapping of Client Portal fields to GHL custom fields
  • Link campaigns to the GHL location via sales_campaigns.ghl_location_id

Close CRM:

  • Configure the create-close-lead edge function webhook handler
  • Verify lead creation works with a test prospect

7. Populate Market Attorneys​

Run the populate-market edge function to fill the market with matching attorneys from the enriched attorneys table:

curl -X POST \
  https://<supabase-url>/functions/v1/populate-market \
  -H "Authorization: Bearer <service-role-key>" \
  -H "Content-Type: application/json" \
  -d '{"market_id": "<market-uuid>"}'

This matches attorneys based on the market's practice area, geography, seniority, and firm tier filters.

8. Send Welcome Email​

Trigger the onboarding email via send-onboarding-email:

curl -X POST \
  https://<supabase-url>/functions/v1/send-onboarding-email \
  -H "Authorization: Bearer <service-role-key>" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "<client-uuid>"}'

This sends a welcome email via Resend with login instructions and next steps.

Post-Onboarding Verification​

After completing all steps, verify:

  • Client can log in and see their workspace dashboard
  • Markets appear in the sidebar with correct names
  • Calendar is connected (green status indicator)
  • At least one booking link is active
  • Market has populated attorneys (check count on market page)
  • If GHL is configured: test prospect syncs correctly
  • Welcome email was received

Common Issues During Onboarding​

IssueFix
User cannot log inCheck Supabase Auth for the user; resend invite if needed
Workspace is emptyVerify user_profiles.client_id matches the client record
Market shows 0 attorneysRun populate-market; ensure attorneys are enriched for the target firms
Calendar OAuth failsCheck redirect URLs in Google/Outlook app config
Booking link 404sVerify the slug is unique and the booking link is_active = true