Skip to main content
A freshly created HQ workspace starts not onboarded. Until onboarding completes, the workspace can be blocked from normal API access — the onboarding wizard endpoints drive it the rest of the way. This guide walks the flow: read the current status, live-validate a business domain before submit, confirm the domain, and mark onboarding complete. All requests are authenticated with a personal access token:
Setting the domain and completing onboarding require the admin scope (security(("bearer_pat" = ["admin"]))); a non-admin caller gets a 403. Reading status and checking a domain only require an authenticated caller.

​
The flow

1

Check onboarding status

Start by reading where the workspace stands. The response tells you what’s left to do and which wizard track applies.
Fields:
  • completed (bool) — whether onboarding has finished.
  • domain_confirmed (bool) — whether the business domain has been confirmed.
  • business_domain (string or null) — the configured business domain, if any.
  • track (string) — the wizard track the SPA should render: slack, teams, or web. It is derived from the workspace’s primary corpus source (a slack source wins, then teams, otherwise web).
See Get onboarding status.
2

Live-validate a domain

Before submitting, pre-check the value the user typed so a typo is caught early. Pass the candidate as the domain query parameter:
The response reports:
  • valid_format (bool) — whether the input normalizes to a usable bare host.
  • normalized (string) — the normalized host (scheme, www., path/query stripped, lowercased). Present only when the format is valid.
  • resolves (bool) — whether that host resolves to at least one usable public address.
When the input doesn’t look like a domain, the response is just { "valid_format": false, "resolves": false } (no normalized field).
The check normalizes before resolving, so https://www.Acme.com/contact and acme.com both collapse to acme.com. A host that resolves only into a private or internal range reports resolves: false.
See Check a domain.
3

Set and confirm the domain

Once the candidate looks good, submit it. The request body is a single domain field:
The server re-normalizes and re-validates the value, then confirms it (this sets domain_confirmed in the status) and kicks off a profile crawl of that website. The API is the boundary, so it does not trust the live pre-check:
  • An invalid or unresolvable domain is rejected with 400.
  • A non-admin caller is rejected with 403.
See Set onboarding domain.
4

Complete onboarding

Finally, mark the workspace complete. This lifts the onboarding gate that can otherwise block normal API access for a new workspace.
The call is idempotent — it only stamps the completion time if onboarding wasn’t already complete, so calling it twice is safe. A non-admin caller is rejected with 403.See Complete onboarding.

​
Putting it together

Re-read status after completing to confirm the gate is lifted:
completed: true is the signal that the workspace is fully onboarded; domain_confirmed: true with a non-null business_domain reflects a successful domain step.