Declare a counterparty's default transaction category
well_set_counterparty_default_categoryDeclare what spend at ONE counterparty is — asked once about the counterparty, instead of once per transaction.
REQUIRED: company_id, from well_list_counterparties. category — a LABEL from the closed list this schema carries. The vocabulary is fixed: there is no free-text category and no way to mint one.
This is the counterparty's DEFAULT, not one row's category. Every transaction of this counterparty categorized from here on takes the label without a model call.
It also reaches backward. The counterparty's existing transactions are relabelled too, in the background over the minutes or hours after the call. Rows a person answered are never touched: a transaction someone categorized or confirmed by hand keeps what they gave it. Tell the user a declaration rewrites the counterparty's history, so they are not surprised by it. To change ONE row instead, use well_set_transaction_category, which sets that transaction and leaves the counterparty alone.
A declaration is trusted at once. The other way a counterparty gets a default is by being taught: three corrections to the same category on three distinct transactions. A declaration skips that, because the person has already said what the answer is.
It overrides whatever the counterparty carried before, including a category the system had inferred from corrections and one an earlier declaration already wrote onto these same rows. A later transaction-level correction still wins over the declaration on the row it names, and teaches the counterparty that the default is wrong.
Do not declare a default for a counterparty whose spend has more than one nature. A marketplace or a cloud vendor selling hardware, compute and advertising to the same buyer has no single answer, and a declaration would state one. Leave those to the classifier and correct them per line.
Not for the workspace's own company. A default is about the other party; the server refuses it on the own company.
The list depends on the workspace. A personal space files household categories, a company workspace business categories, and both file the shared ones. A label outside the workspace's list writes nothing and returns refusal_reason with allowed_categories: send a label from that list.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | The category label spend at this counterparty defaults to. Must be one of the labels in this list. | |
| company_id | Yes | The counterparty to declare a default for, from well_list_counterparties. | |
| 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. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| success | Yes | ||
| category | No | The label the counterparty's default now carries. | |
| company_id | No | ||
| company_name | No | ||
| refusal_reason | No | Set when the category is not in this workspace's list. Nothing was written. | |
| 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. | |
| allowed_categories | No | With refusal_reason: the categories this workspace files and is offered. Send `label` back; `name` is how the workspace shows it. | |
| 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. |