Onboarding API

The Onboarding API manages the new organization setup wizard, tracking progress through configuration steps.

Onboarding Progress Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  current_step: string;          // Current step identifier
  completed_steps: string[];     // Array of completed step identifiers
  skipped_steps: string[];       // Array of skipped step identifiers
  step_data: object;             // Data collected during onboarding
  completed_at?: string;         // ISO timestamp when onboarding completed
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

Onboarding Steps

Get Progress

Retrieve the current onboarding progress for the organization.

Procedure: onboarding.getProgress

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/onboarding.getProgress" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "organization_id": "org-uuid",
        "current_step": "channels",
        "completed_steps": ["welcome", "organization", "team", "business_hours"],
        "skipped_steps": [],
        "step_data": {
          "organization": {
            "name": "Acme Support",
            "domain": "acme.com"
          },
          "team": {
            "invited_count": 3
          },
          "business_hours": {
            "timezone": "America/New_York"
          }
        },
        "completed_at": null,
        "created_at": "2024-01-15T10:00:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Update Progress

Update onboarding progress with data from the current step. Admin only.

Procedure: onboarding.updateProgress

Authentication: Required (Admin)

Input:

{
  step: string;           // Step identifier
  data?: object;          // Data to store for this step
}

Example:

curl -X POST "https://your-domain.com/api/trpc/onboarding.updateProgress" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "step": "organization",
      "data": {
        "name": "Acme Support",
        "domain": "acme.com",
        "logo_url": "https://example.com/logo.png"
      }
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "current_step": "organization",
        "step_data": {
          "organization": {
            "name": "Acme Support",
            "domain": "acme.com",
            "logo_url": "https://example.com/logo.png"
          }
        },
        "updated_at": "2024-01-15T10:35:00.000Z"
      }
    }
  }
}

Complete Step

Mark a step as completed and advance to the next step. Admin only.

Procedure: onboarding.completeStep

Authentication: Required (Admin)

Input:

{
  step: string;  // Step identifier to mark as complete
}

Example:

curl -X POST "https://your-domain.com/api/trpc/onboarding.completeStep" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"step":"team"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "current_step": "business_hours",
        "completed_steps": ["welcome", "organization", "team"],
        "updated_at": "2024-01-15T10:40:00.000Z"
      }
    }
  }
}

Skip Step

Skip a step and advance to the next. Admin only.

Procedure: onboarding.skipStep

Authentication: Required (Admin)

Input:

{
  step: string;  // Step identifier to skip
}

Example:

curl -X POST "https://your-domain.com/api/trpc/onboarding.skipStep" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"step":"team"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "current_step": "business_hours",
        "completed_steps": ["welcome", "organization"],
        "skipped_steps": ["team"],
        "updated_at": "2024-01-15T10:40:00.000Z"
      }
    }
  }
}

Reset Onboarding

Reset onboarding progress to start over. Admin only.

Procedure: onboarding.reset

Authentication: Required (Admin)

Input: None

Example:

curl -X POST "https://your-domain.com/api/trpc/onboarding.reset" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "current_step": "welcome",
        "completed_steps": [],
        "skipped_steps": [],
        "step_data": {},
        "completed_at": null,
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Step Flow

welcome → organization → team → business_hours → channels → complete

Each step can be:

• Completed - User finished the step
• Skipped - User chose to skip (can be revisited later)

When current_step reaches complete, the completed_at timestamp is set.

Use Cases

Onboarding Wizard

// Get current progress
const progress = await trpc.onboarding.getProgress.query()

// Render current step component
switch (progress.current_step) {
  case 'welcome':
    return <WelcomeStep />
  case 'organization':
    return <OrganizationStep data={progress.step_data.organization} />
  case 'team':
    return <TeamStep />
  // ...
}

Saving Step Data

// Save organization details
await trpc.onboarding.updateProgress.mutate({
  step: 'organization',
  data: {
    name: formData.name,
    domain: formData.domain,
  },
})

// Mark step as complete
await trpc.onboarding.completeStep.mutate({
  step: 'organization',
})

Error Codes