curl --request PUT \
  --url https://api.monaco.com/v1/accounts/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain_lookup": "acme.com",
  "linkedin_url": "https://linkedin.com/company/acme",
  "name": "Acme Corp",
  "status": "NEW",
  "notes": "Key enterprise prospect",
  "owner": "550e8400-e29b-41d4-a716-446655440000",
  "tags": [
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "custom_field_7a1c9e2b-3f4d-4a8e-9b1c-2d3e4f5a6b7c": "high"
}
'

{
  "data": {
    "id": "acc_abc123",
    "name": "Acme Corp",
    "status": "NEW",
    "owner": {
      "id": "usr_abc123",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "notes": "Key enterprise prospect",
    "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"
    },
    "scoring": {
      "tier": "A",
      "heat_score": "Hot"
    },
    "tags": [
      "Enterprise"
    ],
    "created_at": "2025-06-15T10:30:00Z",
    "updated_at": "2025-06-15T10:30:00Z",
    "custom_field_7a1c9e2b-3f4d-4a8e-9b1c-2d3e4f5a6b7c": "high"
  },
  "meta": {
    "timestamp": "2026-04-21T12:00:00Z"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "domains": [
      {
        "domain": "acme.com",
        "reason": "conflict",
        "account_id": "<string>",
        "account_name": "Acme Corp"
      }
    ]
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

Accounts

Upsert an Account

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/, 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

accounts

curl --request PUT \
  --url https://api.monaco.com/v1/accounts/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain_lookup": "acme.com",
  "linkedin_url": "https://linkedin.com/company/acme",
  "name": "Acme Corp",
  "status": "NEW",
  "notes": "Key enterprise prospect",
  "owner": "550e8400-e29b-41d4-a716-446655440000",
  "tags": [
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "custom_field_7a1c9e2b-3f4d-4a8e-9b1c-2d3e4f5a6b7c": "high"
}
'

{
  "data": {
    "id": "acc_abc123",
    "name": "Acme Corp",
    "status": "NEW",
    "owner": {
      "id": "usr_abc123",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "notes": "Key enterprise prospect",
    "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"
    },
    "scoring": {
      "tier": "A",
      "heat_score": "Hot"
    },
    "tags": [
      "Enterprise"
    ],
    "created_at": "2025-06-15T10:30:00Z",
    "updated_at": "2025-06-15T10:30:00Z",
    "custom_field_7a1c9e2b-3f4d-4a8e-9b1c-2d3e4f5a6b7c": "high"
  },
  "meta": {
    "timestamp": "2026-04-21T12:00:00Z"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "domains": [
      {
        "domain": "acme.com",
        "reason": "conflict",
        "account_id": "<string>",
        "account_name": "Acme Corp"
      }
    ]
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

Body

application/json

Request body for upserting an account, by domain_lookup or by id.

domain is the deprecated name for domain_lookup; it is folded into domain_lookup before validation and mirrored back so the create payload, which maps domain, still receives it. Custom fields can be passed as additional keys prefixed with custom_field_.

company_name

string | null

Company name

Example:

"Acme Corporation"

linkedin_url

string | null

LinkedIn company page URL for matching or creating the account

Example:

"https://linkedin.com/company/acme"

description

string | null

Company description

employee_count

integer | null

Number of employees

Required range: x >= 0

Example:

250

founded_year

integer | null

Year the company was founded

Example:

2019

estimated_annual_revenue_usd

number | null

Estimated annual revenue in USD

Required range: x >= 0

Example:

12000000

total_funding_usd

number | null

Total funding raised in USD

Required range: x >= 0

Example:

50000000

last_funding_round

enum<string> | null

Type of the most recent funding round

Available options:

pre_seed,

seed,

angel,

series_a,

series_b,

series_c,

series_d,

series_e,

series_f,

series_g,

series_h,

series_i,

series_j,

series_unknown,

private_equity,

debt_financing,

convertible_note,

grant,

non_equity_assistance,

corporate_round,

equity_crowdfunding,

product_crowdfunding,

initial_coin_offering,

secondary_market,

post_ipo_equity,

post_ipo_debt,

post_ipo_secondary,

undisclosed

Example:

"series_b"

last_funding_date

string<date> | null

Date of the most recent funding round

Example:

"2024-03-15"

industries

string[] | null

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

Example:

["Software", "Artificial Intelligence"]

business_model

enum<string> | null

Business model

Available options:

B2B,

B2C

Example:

"B2B"

company_status

enum<string> | null

Operating status of the company

Available options:

active,

acquired,

out_of_business,

ipo,

unknown

Example:

"active"

location

string | null

Headquarters as city, state, country

Example:

"San Francisco, CA, United States"

string<uuid> | null

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

domain_lookup

string | null

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.

Example:

"acme.com"

domain

string | null

deprecated

Deprecated: use domain_lookup.

Example:

"acme.com"

domains

string[] | null

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

Maximum array length: 500

Example:

["acme.com", "acme.io"]

clear_fields

enum<string>[] | null

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

Standard fields an update by id can clear; PATCH writes a null to each of these.

status is absent because a null status means "unchanged" downstream.

Available options:

name,

notes,

owner,

parent_account,

company_id,

company_name,

linkedin_url,

description,

employee_count,

founded_year,

estimated_annual_revenue_usd,

total_funding_usd,

last_funding_round,

last_funding_date,

industries,

business_model,

company_status,

location

Example:

["owner"]

name

string | null

Display name for the account

Example:

"Acme Corp"

status

string | null

Account status

Example:

"NEW"

notes

string | null

Notes about the account

Example:

"Key enterprise prospect"

owner

string<uuid> | null

User ID to assign as account owner

Response

Successful Response

data

AccountWriteResponse · object

required

Account returned by a single-account update.

Show child attributes

API

MCP

Upsert an Account

Body

Response