Set Account State

PUT

account-states

{companyId}

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}'

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}'

{
  "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
    }
  }
}

{
  "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
    }
  }
}

{
  "success": false,
  "error": { "message": "tier_id does not reference a tier in this workspace", "code": "BAD_REQUEST" }
}

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.

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

Path Parameters

string

required

The account’s company_id (the company UUID).

Body

string

A tier id from List Account Tiers, or "" to clear.

string

An owner id from List Owners, or "" to clear.

boolean

Dismiss the account (and every path there) or restore it. See Account States — dismiss hides, a tag never does.

string

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.

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 instead. It is no longer returned in the response.

Response Fields

object

The stored state: company_id, tier_id, owner_id, is_discarded, notes, updated_at, updated_by.

integer

How many warm intros followed an is_discarded change at this account. 0 when the write did not touch the flag.

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.

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}'

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}'

{
  "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
    }
  }
}

{
  "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
    }
  }
}

{
  "success": false,
  "error": { "message": "tier_id does not reference a tier in this workspace", "code": "BAD_REQUEST" }
}

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}'

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}'

{
  "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
    }
  }
}

{
  "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
    }
  }
}

{
  "success": false,
  "error": { "message": "tier_id does not reference a tier in this workspace", "code": "BAD_REQUEST" }
}

API Reference

Import

Search

Jobs

Network

Opportunities

Owners

Accounts

Account States

Saved Views

Workflows

Intro Requests

Record Activity

Lists

Tags

Account Tags

Target Accounts

Client Companies

ICP

Competitor Monitoring

Connector Refresh

Notifications

Set Account State

Path Parameters

Body

Response Fields

​Path Parameters

​Body

​Response Fields

Path Parameters

Body

Response Fields