> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Account State

> Set one account's tier, owner, or discard flag

Upsert. Only provided fields change.

Tags are not set here: they are shared by accounts, people and opportunities and
have their own endpoint,
[Set An Account's Tags](/api-reference/set-account-record-tags).

<Warning>
  **An empty string on `tier_id` or `owner_id` clears that reference.** Omitting
  the field leaves it alone — send an explicit `""` to clear it.
</Warning>

## Path Parameters

<ParamField path="companyId" type="string" required>
  The account's `company_id` (the company UUID).
</ParamField>

## Body

<ParamField body="tier_id" type="string">
  A tier id from [List Account Tiers](/api-reference/list-tiers), or `""` to
  clear.
</ParamField>

<ParamField body="owner_id" type="string">
  An owner id from [List Owners](/api-reference/list-owners), or `""` to clear.
</ParamField>

<ParamField body="is_discarded" type="boolean">
  Dismiss the account (and every path there) or restore it. See [Account
  States](/account-states) — dismiss hides, a tag never does.
</ParamField>

<ParamField body="notes" type="string" />

<ParamField body="push_to_crm" type="boolean" default="false">
  Also write the owner to the matched CRM company. Ignored without `owner_id`,
  and a cleared owner is never pushed. A mapping set to "Clustr sets the value"
  pushes regardless; "Your CRM sets the value" and paused never do. `pushToCrm`
  is accepted as the same flag.
</ParamField>

<ParamField body="status_id" type="string" deprecated>
  **Deprecated — a status is a tag.** The id still works: it names the account
  tag the former status became, and this writes that tag (replacing the group's
  previous tag, since the group is single-choice). `""` clears that group. Use
  [Set An Account's Tags](/api-reference/set-account-record-tags) instead. It is
  no longer returned in the response.
</ParamField>

## Response Fields

<ResponseField name="account_state" type="object">
  The stored state: `company_id`, `tier_id`, `owner_id`, `is_discarded`,
  `notes`, `updated_at`, `updated_by`.
</ResponseField>

<ResponseField name="intros_moved" type="integer">
  How many warm intros followed an `is_discarded` change at this account. `0`
  when the write did not touch the flag.
</ResponseField>

<ResponseField name="crmPush" type="object">
  Present only when an owner was written and the CRM was involved.

  * `status` — `pushed`, `refused`, `failed` or `skipped`
  * `reason` — a machine code, e.g. `direction_crm_owns`, `owner_not_in_crm`,
    `owner_deactivated`, `record_not_matched`, `clear_not_pushed`,
    `writes_disabled`, `crm_not_connected`
  * `message` — one sentence written for a person. Provider errors are logged,
    never returned here
  * `provider` — the CRM written to
  * `pushed` / `notPushed` — record counts, for a write that covered several

  The owner is saved in Clustr whatever this says.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.clustr-ai.com/api/public/account-states/9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"tier_id": "1a2b3c4d-5e6f-4071-8a92-b3c4d5e6f708", "is_discarded": false}'
  ```

  ```bash cURL (owner, and push it to the CRM) theme={null}
  curl -X PUT "https://api.clustr-ai.com/api/public/account-states/9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"owner_id": "3f2b1c40-8a11-4f2e-9d61-0f5a8c7a2b13", "push_to_crm": true}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "account_state": {
        "company_id": "9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
        "tier_id": "1a2b3c4d-5e6f-4071-8a92-b3c4d5e6f708",
        "owner_id": "3f2b1c40-8a11-4f2e-9d61-0f5a8c7a2b13",
        "is_discarded": false,
        "notes": "",
        "updated_at": "2026-09-16T10:00:00Z",
        "updated_by": null
      },
      "intros_moved": 0,
      "crmPush": {
        "status": "pushed",
        "provider": "hubspot",
        "pushed": 1,
        "notPushed": 0
      }
    }
  }
  ```

  ```json 200 (the CRM refused) theme={null}
  {
    "success": true,
    "data": {
      "account_state": { "company_id": "9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "owner_id": "3f2b1c40-8a11-4f2e-9d61-0f5a8c7a2b13" },
      "intros_moved": 0,
      "crmPush": {
        "status": "refused",
        "reason": "owner_not_in_crm",
        "message": "Anna has no HubSpot user",
        "provider": "hubspot",
        "pushed": 0,
        "notPushed": 1
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": { "message": "tier_id does not reference a tier in this workspace", "code": "BAD_REQUEST" }
  }
  ```
</ResponseExample>