Create the company workspace
well_create_company_workspaceCreate the company workspace from a candidate, the step that turns a picked company into a workspace the close runs in. This anchors the candidate's company as the new workspace's own company and links it to the membership it was created under.
REQUIRED: candidate_id — from well_create_company_candidate. This mints the child workspace, projects its accounting settings from the country defaults, anchors its own company, and writes the lineage row, so well_switch_workspace can move into it in the same conversation. Idempotent: calling it again on the same candidate returns the same child, with already_anchored true.
OPTIONAL, the person's two answers: bring_company_data (true brings the company's history into its workspace: its documents, tasks, transactions and accounts) and move_connectors (true moves the person's bank and accounting connections into the company workspace). Before calling, confirm the company with the person and ask both questions: bring its history (default yes) and move the bank and accounting connections (the card shows it on by default). Pass each answer as true or false exactly as the person gave it, and ask again when an answer is unclear. Omitting move_connectors records "do not move": the connections move only when the person says yes, through the card or in the chat. Omitting bring_company_data means true.
After a successful mint, history reports the stored history choice and preview counts, and connector_move reports the stored connector-move state. Tell the person with these sentences only, translated when they write in another language, and never write a field name, a state or refusal literal, an id or a unit count. history.brought false: "The company's earlier items stay where they are, and nothing was brought into the new workspace." true with counts null: "The company's earlier documents, tasks, transactions and accounts are being linked to the new workspace." true with counts: "N documents, N tasks, N transactions and N accounts will be linked to the new workspace." (more than N when capped; "are linked" only when adoption_status is complete). connector_move.state armed: "Your bank and accounting connections are being moved to the new workspace, and this takes a while." nothing_to_move: "There are no bank or accounting connections to move." pending: "The move of your bank and accounting connections is being set up." refused, whatever the refusal: "Your bank and accounting connections stay where they are, because Well could not move them." not_requested or null: no sentence.
OPTIONAL: existing_workspace_id — when well_get_own_company returned it on the candidate, the person already has a workspace for that company. Pass the id and this call attaches that workspace under this one instead of minting a duplicate: with relation child it already sits under this workspace, with relation top_level it is linked under it. The two answers still apply: the stored choice keeps or brings the history, and the move runs after the call, never before it. Never invent or reuse an id the read did not return; a candidate that carries none mints as before, and one whose offer is stale is refused rather than duplicated.
Only a workspace owner or admin may create the company workspace. A caller without that role is refused, not silently ignored. Confirm the company with the user before calling.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| candidate_id | Yes | The candidate id returned by well_create_company_candidate. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| move_connectors | No | The person's answer to: move your bank and accounting connections into the company workspace? true moves them, false keeps them where they are. Ask first. Omitting records false: nothing moves unless the person opted in. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. | |
| bring_company_data | No | The person's answer to: bring the company's history into its workspace (documents, tasks, transactions and accounts)? true brings it, false leaves it. Omit only when the person was not asked; omitting means true. | |
| existing_workspace_id | No | The existing workspace's id when well_get_own_company returned one on this candidate: the person already has a workspace for that company, and passing the id attaches it under this one instead of minting a duplicate. Never pass an id the read did not return; leave it out for any candidate that carries none. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The company workspace's name, derived from the candidate. | |
| error | No | ||
| history | No | The stored history choice and the pre-mint counts of items that will be linked. | |
| success | Yes | ||
| workspace_id | No | The created (or existing) company workspace's id. | |
| connector_move | No | The stored connector-move intent and its derived state; only armed means connections are moving. | |
| own_company_id | No | The public id of the company anchored as the workspace's own. | |
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| already_anchored | No | True when this call did not mint a fresh workspace: the candidate had already minted its child (a converged replay) or resolved to a company already anchored on the caller. The same child is returned either way. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |