Update an Account

PATCH /accounts/{account_id}

Update Account

cURL

curl --request PATCH \
  --url https://api.example.com/accounts/{account_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "domain": "<string>",
  "website": "<string>",
  "size_range": "<string>",
  "annual_revenue": 123,
  "linkedin_url": "<string>",
  "address": {},
  "tags": [
    "<string>"
  ],
  "custom_fields": {},
  "lifecycle_stage": "<string>",
  "notes": "<string>"
}
'

422

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Every field is optional — send only what you want to change. tags, address, and custom_fields are wholesale replacements of the column, not merges.

PATCH only ever sets fields you explicitly include with a non-null value. The patch body is built by dropping every null/omitted field before sending it to the database — so {"domain": null} does not clear the domain, it’s indistinguishable from not sending domain at all. There’s currently no way to null out a previously-set field through this endpoint.

industry is a closed enum, not free text — it accepts exactly one of the AccountIndustry values, and anything else fails validation with 422. An empty string ("") is treated as unset (i.e. a no-op, per the note above), not a validation error.

lifecycle_stage is checked in application code, not just the DB. Valid values are prospect, customer, churned, inactive — anything else is rejected with 400 before the write happens (the same values are also enforced by a CHECK constraint on the table).

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

The full updated account row — every column on accounts (id, org_id, name, domain, industry, size_range, annual_revenue, health_score, website, linkedin_url, address, tags, custom_fields, created_by, created_at, updated_at, owner_id, lifecycle_stage, notes).

Errors

Status	Cause
400 Bad Request	No fields in the body (after dropping nulls), an empty/whitespace-only name, an invalid lifecycle_stage, or no active organization on the token.
404 Not Found	No account with this id in the caller’s organization.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

account_id · string · required

The account's id.

Body

application/json

name · string | null

New name; empty/whitespace-only is rejected.

domain · string | null

New primary domain.

industry · enum<string> | null

One AccountIndustry enum value; blank/omitted means unset.

Available options: Food & Beverage, Technology, Healthcare, Financial Services, Retail, Manufacturing, Professional Services, Real Estate, Education, Media & Entertainment, Transportation & Logistics, Energy, Agriculture, Construction, Hospitality & Travel, Other

website · string | null

New company website URL.

size_range · string | null

Freeform employee-count bucket, e.g. '11-50'.

annual_revenue · number | null

Annual revenue.

linkedin_url · string | null

Company LinkedIn profile URL.

address · Address · object | null

Freeform postal address JSON, stored as-is.

tags · string[] | null

Full replacement list of tag name strings.

custom_fields · Custom Fields · object | null

Full replacement JSON object of custom field values.

lifecycle_stage · string | null

One of prospect, customer, churned, inactive.

notes · string | null

Free-text notes.

Response

200

application/json

Successful Response