Accounts

Upsert an Account

Changed on Nov 3, 2026

Creates a new account or updates an existing one. domain_lookup is the matching identifier (domain is its deprecated name).

Accounts without a domain — where the workspace allows accounts without a company, omit domain_lookup and pass name to create an account with no company or domain. Every such request creates a new account; it never matches an existing one by name.

Duplicate resolution — an exact domain_lookup match is updated in place, otherwise an account is created (a company record for the domain must exist in our data sources).

Update by id — with id, that account is updated and never created; an unknown id returns 404. domains replaces the domain list as on PATCH /v1/accounts/{account_id}, as do company_id and replace_edited_fields. List company_id in clear_fields to unlink. Null fields are left unchanged; list fields to clear in clear_fields. Requires a user-scoped key.

Enrichment — creation synchronously enriches the account with firmographic data (industry, employee count, funding), so requests can take several seconds. Use generous timeouts (10s+) and keep creates off hot paths.

put/v1/accounts/

Request

Base URL
https://api.monaco.com
URL
https://api.monaco.com/v1/accounts/
Auth
none declared

Request body

linkedin_urlstring nullable

LinkedIn company page URL for matching or creating the account

descriptionstring nullable

Company description

employee_countinteger nullable

Number of employees

founded_yearinteger nullable

Year the company was founded

estimated_annual_revenue_usdnumber nullable

Estimated annual revenue in USD

total_funding_usdnumber nullable

Total funding raised in USD

Type of the most recent funding round

last_funding_datestring date nullable

Date of the most recent funding round

industriesstring[] nullable

Industries from Monaco's standard list. Replaces the current list

business_model'B2B' | 'B2C' nullable

Business model

company_status'active' | 'acquired' | 'out_of_business' | 'ipo' | 'unknown' nullable

Operating status of the company

locationstring nullable

Headquarters as city, state, country

idstring uuid nullable

ID of an existing account to update. If set, the account is updated by ID instead of matched by domain_lookup.

domain_lookupstring nullable

Domain used to find the account, or to create it if none matches. Omit it to create an account from name alone, where the workspace allows accounts without a company; every such call creates a new account. Not allowed when id is present.

domainstring nullable

Deprecated: use domain_lookup.

domainsstring[] nullable

The account's full ordered list of domains to update. Only applies when id is present. [] removes all.

clear_fieldsAccountClearableField[] nullable

Fields to clear on the account. Only applies when id is present.

namestring nullable

Display name for the account

statusstring nullable

Account status

notesstring nullable

Notes about the account

ownerstring uuid nullable

User ID to assign as account owner

tagsstring[] nullable

Tag IDs to associate with the account. Appended to the account's existing tags.

parent_accountstring uuid nullable

Account ID to set as this account's parent. Must be a top-level account in the same workspace.

company_idstring uuid nullable

ID of the company to link

replace_edited_fieldsboolean nullable

Also replace fields a user has edited

Example request

{
  "linkedin_url": "https://linkedin.com/company/acme",
  "employee_count": 250,
  "founded_year": 2019,
  "estimated_annual_revenue_usd": 12000000,
  "total_funding_usd": 50000000,
  "last_funding_round": "series_b",
  "last_funding_date": "2024-03-15",
  "industries": [
    "Software",
    "Artificial Intelligence"
  ],
  "business_model": "B2B",
  "company_status": "active",
  "location": "San Francisco, CA, United States",
  "domain_lookup": "acme.com",
  "domain": "acme.com",
  "domains": [
    "acme.com",
    "acme.io"
  ],
  "clear_fields": [
    "owner"
  ],
  "name": "Acme Corp",
  "status": "NEW",
  "notes": "Key enterprise prospect"
}

Response

Successful Response

Example response

{
  "data": {
    "id": "acc_abc123",
    "name": "Acme Corp",
    "status": "PROSPECTING",
    "owner": {
      "id": "usr_abc123",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "parent_account": {
      "id": "acc_abc123",
      "name": "Acme Holdings"
    },
    "notes": "Key enterprise prospect",
    "domains": [
      "acme.com",
      "acme.io"
    ],
    "company": {
      "domain": "acme.com",
      "linkedin_url": "https://linkedin.com/company/acme",
      "description": "Enterprise software company specializing in AI-driven sales tools",
      "employee_count": 250,
      "founded_year": 2019,
      "industries": [
        "Software",
        "Artificial Intelligence"
      ],
      "total_funding_usd": 50000000,
      "last_funding_date": "2024-03-15",
      "company_name": "Acme Corporation",
      "estimated_annual_revenue_usd": 12000000,
      "last_funding_round": "series_b",
      "business_model": "B2B",
      "company_status": "active",
      "location": "San Francisco, CA, United States"
    },
    "overridden_fields": [
      "industries",
      "domains"
    ],
    "scoring": {
      "tier": "A",
      "heat_score": "Hot"
    },
    "tags": [
      "Enterprise",
      "High Priority"
    ],
    "created_at": "2025-06-15T10:30:00Z",
    "updated_at": "2025-06-15T10:30:00Z",
    "last_activity_at": "2025-06-15T10:30:00Z",
    "last_activity_type": "outbound_email",
    "last_contacted_at": "2025-06-15T10:30:00Z",
    "last_contacted_type": "email",
    "last_inbound_at": "2025-06-15T10:30:00Z",
    "last_inbound_type": "email",
    "skipped_domains": [
      {
        "domain": "acme.com",
        "reason": "conflict",
        "account_name": "Acme Corp"
      }
    ]
  }
}

Changes

Nov 3, 2026fc720ada2a81 Revision changes
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  the request property became optional
- info
  request property deprecated
- info
  request property list-of-types was widened by adding types null to media type application/json
- info
  added the non-success response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property /// to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status

Operation history