useCapxulCompleteOrganizationOnboarding

Mutation hook that completes organization onboarding — saves the founder's profile, creates the org, and returns the org plus lifecycle snapshot.

Completes organization onboarding after the founder's first sign-in: persists their personal identity profile, creates the organization, triggers account setup, and returns the created org plus a lifecycle snapshot to route on. For individual users, use useCapxulCompletePersonalOnboarding instead.

Import

import { useCapxulCompleteOrganizationOnboarding } from "@capxul/sdk-react";

Usage

"use client";

import { useState } from "react";
import { useCapxulCompleteOrganizationOnboarding } from "@capxul/sdk-react";
import { useRouter } from "next/navigation";

function OrganizationOnboardingForm() {
  const router = useRouter();
  const completeOrg = useCapxulCompleteOrganizationOnboarding();
  const [organizationName, setOrganizationName] = useState("");
  const [handle, setHandle] = useState("");
  const [country, setCountry] = useState("");
  const [ownerDisplayName, setOwnerDisplayName] = useState("");

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        const { org, lifecycle } = await completeOrg.mutateAsync({
          organizationName: organizationName.trim(),
          handle: handle.trim(),
          country: country.trim(),
          ownerDisplayName: ownerDisplayName.trim(),
        });
        console.log(`Created ${org.name} (${org.id})`);
        router.push(lifecycle.status === "ready" ? "/dashboard" : "/signup/provisioning");
      }}
    >
      <input required value={organizationName} onChange={(e) => setOrganizationName(e.target.value)} />
      <input required placeholder="acme-co" value={handle} onChange={(e) => setHandle(e.target.value)} />
      <input required value={ownerDisplayName} onChange={(e) => setOwnerDisplayName(e.target.value)} />
      <input required placeholder="GH" value={country} onChange={(e) => setCountry(e.target.value)} />
      <button type="submit" disabled={completeOrg.isPending}>
        {completeOrg.isPending ? "Creating…" : "Create organization"}
      </button>
      {completeOrg.error ? <p>{completeOrg.error.message}</p> : null}
    </form>
  );
}

Call it from a submit handler and route on lifecycle.status, exactly like personal onboarding. Keep the returned org.id — every later org call is scoped by it (the org-scoped hooks such as useCapxulOrgTreasury take the org id as their first parameter).

Parameters

The hook itself takes no parameters. The mutation takes a CompleteOrganizationOnboardingInput:

Field	Type	Description
`organizationName`	`string`	The organization's display name. Required.
`handle`	`string`	The globally-unique org slug (e.g. `"acme-co"`). Required.
`country`	`string`	ISO-3166 country code (e.g. `"GH"`). Required.
`ownerDisplayName`	`string`	The founder's personal display name — this also creates their identity profile. Required.

Return type

import { type UseCapxulCompleteOrganizationOnboardingReturn } from "@capxul/sdk-react";
// UseMutationResult<CompleteOrganizationOnboardingResult, CapxulError, CompleteOrganizationOnboardingInput>

On success, data is { org, lifecycle }:

org — the created organization: its id, name, handle, your role in it, and its treasury Account.
lifecycle — the account-setup snapshot; lifecycle.status is the routing source of truth, documented on the useCapxulAccountLifecycle page.

The hook returns TanStack Query's UseMutationResult. The most-used fields:

Field	Description
`mutate`	Fire the mutation (fire-and-forget; pair with `onSuccess`/`onError` callbacks).
`mutateAsync`	Fire the mutation and get a `Promise` of the result. Rejects with a `CapxulError` on failure.
`data`	The mutation result (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last attempt failed, otherwise `null`.
`isPending`	`true` while the mutation is in flight. Use it to disable submit buttons.
`reset`	Clear the mutation state (`data`, `error`) back to idle.

Mutations do not retry by default. The full field list is in the TanStack Query useMutation reference; see also the TanStack Query integration guide.

Cache behavior

On success this mutation invalidates:

["capxul", "profile"] (useCapxulProfile) — the founder's profile is no longer null.
["capxul", "accountLifecycle"] (useCapxulAccountLifecycle).
["capxul", "orgs"] (useCapxulOrgs) — the org list now includes the new organization.

Errors

Failures surface as a CapxulError on error / thrown from mutateAsync — for example a handle that is already taken, an invalid country code, or calling it without a signed-in session.

Client method

This hook wraps client.onboarding.completeOrganization(input) on the core SDK.