---
title: "Upsert an Account"
method: PUT
path: "/v1/accounts/"
tags: ["Accounts"]
---

# Upsert an Account

`PUT /v1/accounts/`

Creates a new account or updates an existing one. `domain` is required and is used as the primary identifier for matching.

**Duplicate resolution** — the request is matched against existing accounts in the org by exact match on `domain`. If a match is found, that account is updated in place with the provided fields and returned; otherwise a new account is created (a company record for the domain must exist in our data sources).

**Enrichment** — on creation, Monaco synchronously enriches the account with company firmographic data (industry, employee count, funding, etc.). This can make create requests take several seconds to complete; clients should use generous timeouts (10s+) and avoid issuing creates on hot paths.

Any `tags` list provided is **appended** to the existing tags on the account.

## Request body

- AccountUpsertRequest — Request body for upserting an account. Custom fields can be passed as additional keys prefixed with ``custom_field_``.
  - `domain` string, required — Company domain for matching or creating the account
  - `linkedin_url` string, nullable — LinkedIn company page URL for matching or creating the account
  - `name` string, nullable — Display name for the account
  - `status` string, nullable — Account status
  - `notes` string, nullable — Notes about the account
  - `owner` string, uuid, nullable — User ID to assign as account owner
  - `tags` string[], nullable — List of tag IDs to associate with the account

## Response `200`

Successful Response

- PublicItemResponseAccountResponse
  - `data` AccountResponse, required — Account resource. Custom fields appear as additional keys prefixed with ``custom_field_``.
    - `id` string, required — Unique identifier for the account
    - `name` string, nullable — Name of the account
    - `status` string, nullable — Current status of the account
    - `owner` OwnerInfo
      - `id` string, required — Unique identifier of the user
      - `first_name` string, nullable — First name of the user
      - `last_name` string, nullable — Last name of the user
    - `notes` string, nullable — Notes about the account
    - `company` CompanyInfo
      - `domain` string, nullable — Primary website domain
      - `linkedin_url` string, nullable — LinkedIn company page URL
      - `description` string, nullable — Company description
      - `employee_count` integer, nullable — Number of employees
      - `founded_year` integer, nullable — Year the company was founded
      - `industries` string[] — List of industry classifications
      - `total_funding_usd` number, nullable — Total funding raised in USD
      - `last_funding_date` string, nullable — Date of the most recent funding round
    - `scoring` ApiPublicApiSchemasAccountsScoringInfo
      - `tier` string, nullable — Firmographic tier
      - `heat_score` string, nullable — Heat score tier
    - `tags` string[] — List of tag names associated with the account
    - `created_at` string, date-time, required — Date and time the account was created
    - `updated_at` string, date-time, required — Date and time the account was last updated
  - `meta` ResponseMeta
    - `timestamp` string, date-time — Server timestamp of the response

## Other responses

- `4XX` — Client error

---

[API](https://skmtc.dev/monaco/apis/monaco-public-api.md) · [All operations](https://skmtc.dev/monaco/apis/monaco-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/monaco/monaco-public-api/revisions/ec4d9b2b035b/schema)