Sign in

v1

latestOpenAPI 3.1.02026-07-263788129.7 KB
Contacts

Upsert a Contact

Creates a new contact or updates an existing one.

Identifiers — either email or linkedin_url must be provided. If only linkedin_url is supplied, you must also provide account_id or domain so the contact can be associated with an account.

Duplicate resolution — the request is matched against existing contacts in the org in this order: (1) exact match on email (case-insensitive), then (2) exact match on linkedin_url. If a match is found, that contact is updated in place with the provided fields and returned; otherwise a new contact is created. Unlike POST /contacts, no 409 is raised on a duplicate identifier — the existing record is updated instead.

Account resolution priority — when creating a new contact, Monaco resolves the contact's account in this order:

  1. account_id (if provided)
  2. domain (if provided)
  3. the domain parsed from email

Enrichment — when this call creates a new contact (no existing match), Monaco synchronously enriches the contact and, if needed, resolves or creates the associated account. This can make those requests take several seconds to complete; clients should use generous timeouts (10s+) and avoid issuing upserts on hot paths.

Any tags list provided is appended to the existing tags on the contact.

put/v1/contacts/

Request body

emailstring nullable

Email address of the contact. Either email or linkedin_url is required.

linkedin_urlstring nullable

LinkedIn profile URL. Either email or linkedin_url is required.

first_namestring nullable

First name of the contact

last_namestring nullable

Last name of the contact

titlestring nullable

Job title of the contact

phone_numberstring nullable

Phone number of the contact

locationstring nullable

Location of the contact

account_idstring uuid nullable

ID of the account to associate the contact with

domainstring nullable

Domain of the contact's company (used for account resolution)

do_not_contactboolean nullable

Whether the contact has opted out of outreach

tagsstring[] nullable

List of tag IDs to associate with the contact

Example request

{
  "email": "jane@acme.com",
  "linkedin_url": "https://linkedin.com/in/janesmith",
  "first_name": "Jane",
  "last_name": "Smith",
  "title": "VP of Engineering",
  "phone_number": "+1-555-123-4567",
  "location": "San Francisco, CA",
  "domain": "acme.com"
}

Response

Successful Response

Example response

{
  "data": {
    "id": "con_abc123",
    "account_id": "acc_def456",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@acme.com",
    "title": "VP of Engineering",
    "phone_number": "+1-555-123-4567",
    "linkedin_url": "https://linkedin.com/in/janesmith",
    "location": "San Francisco, CA",
    "source": "linkedin",
    "notes": "Met at SaaStr 2025",
    "scoring": {
      "heat_score": "Hot"
    },
    "tags": [
      "Interested",
      "Decision Maker"
    ],
    "created_at": "2025-06-15T10:30:00Z",
    "updated_at": "2025-06-15T10:30:00Z"
  }
}