Skip to main content

Onboarding API

The onboarding router tracks per-tenant onboarding state, including business model selection, step completion, and banner dismissal. The onboarding checklist is non-linear -- steps can be completed in any order.

Router namespace: onboarding

Source: src/server/trpc/routers/onboarding.ts

Procedures​

ProcedureTypeAccessDescription
getProgressquerytenantGet full onboarding state
updateStepmutationtenantMark a step complete or incomplete
setBusinessModelmutationtenantSet the tenant's business model
dismissBannermutationtenantHide the onboarding banner

getProgress​

Returns the complete onboarding state for the current tenant, including business model, step completion status, and whether the banner has been dismissed.

onboarding.getProgress.queryOptions()

Input​

None.

Response​

{
  "businessModel": "b2b",
  "steps": {
    "connectCrm": true,
    "mapFields": true,
    "configureScoring": false,
    "runFirstSync": false
  },
  "dismissedBanner": false,
  "completedAt": null
}

When all four steps are complete, completedAt is set to the ISO 8601 timestamp of the final step completion.

Example​

const trpc = useTRPC();
const { data: progress } = useQuery(
  trpc.onboarding.getProgress.queryOptions()
);

const allComplete = progress && Object.values(progress.steps).every(Boolean);

updateStep​

Marks an onboarding step as complete or incomplete. Steps can be toggled in any order.

onboarding.updateStep.mutationOptions(options)

Input​

FieldTypeRequiredDescription
step"connectCrm" | "mapFields" | "configureScoring" | "runFirstSync"YesStep identifier
completedbooleanYesWhether the step is complete

Response​

{
  "success": true
}

Example​

const trpc = useTRPC();
const queryClient = useQueryClient();

const mutation = useMutation(
  trpc.onboarding.updateStep.mutationOptions({
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: trpc.onboarding.getProgress.queryKey(),
      });
    },
  })
);

mutation.mutate({ step: "connectCrm", completed: true });

setBusinessModel​

Sets the tenant's business model, which controls label terminology throughout the dashboard (e.g., "Accounts" vs "Customers" for B2B vs B2C).

onboarding.setBusinessModel.mutationOptions(options)

Input​

FieldTypeRequiredDescription
businessModel"b2b" | "b2c"YesBusiness model selection

Response​

{
  "success": true
}

Example​

const trpc = useTRPC();

const mutation = useMutation(
  trpc.onboarding.setBusinessModel.mutationOptions({})
);

mutation.mutate({ businessModel: "b2b" });
Label Switching

Setting the business model updates the TenantLabelsProvider context. Components using useLabels() will automatically reflect the new terminology.

dismissBanner​

Hides the onboarding banner from the dashboard. The banner can still be accessed from settings. This is a one-way toggle -- there is no procedure to un-dismiss.

onboarding.dismissBanner.mutationOptions(options)

Input​

None.

Response​

{
  "success": true
}

Example​

const trpc = useTRPC();
const queryClient = useQueryClient();

const mutation = useMutation(
  trpc.onboarding.dismissBanner.mutationOptions({
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: trpc.onboarding.getProgress.queryKey(),
      });
    },
  })
);

mutation.mutate();