Tools: Companies and people

upsert_person

Create a person (contact), or update them if one with the same email already exists. Deduplicates on the lowercased email. Only the fields you pass are changed. Link them to a company with company_id (find it with search or upsert_company).

Group	Companies and people
Scope	`crm:write`
Who can call it	Agents and people with this scope.
Kind	Write. Recorded in the change history with who made it.
Retries	Pass `idempotency_key` (MCP) or the `Idempotency-Key` header (REST); a retry with the same key within 24 hours returns the first result.
Widget	In hosts that support MCP Apps, the result shows where the write landed (the changed record, the pipeline, or the updated list).

Parameters

Parameter	Type	Required	Notes
`id`	id (uuid)	no	Update this existing record, including when its dedupe field is missing.
`email`	email	no	The dedupe key. Strongly recommended.
`name`	string	no
`title`	string	no
`company_id`	id (uuid)	no
`custom`	object	no	Values for this workspace's custom fields, by key (see describe_schema). Checked against each field's type; null clears one.
`source`	object { name, url? }	no
`source.name`	string	yes	max 100 characters
`source.url`	string	no

Call it over MCP

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "upsert_person",
    "arguments": {
      "idempotency_key": "log-call-acme-2026-11-02"
    }
  }
}

Send it to https://api.tandemcrm.app/mcp (streamable HTTP). Most people never write this by hand: their agent picks the tool from its description.

Call it over REST

curl -X POST https://api.tandemcrm.app/v1/ops/upsert_person \
  -H "Authorization: Bearer $TANDEM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: log-call-acme-2026-11-02" \
  -d '{}'

Input schema

The JSON Schema the MCP server advertises for this tool (over MCP it also accepts idempotency_key):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "description": "Update this existing record, including when its dedupe field is missing.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "email": {
      "description": "The dedupe key. Strongly recommended.",
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "title": {
      "type": "string"
    },
    "company_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "custom": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Values for this workspace's custom fields, by key (see describe_schema). Checked against each field's type; null clears one."
    },
    "source": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "url": {
          "type": "string",
          "pattern": "^https?:\\/\\/"
        }
      },
      "required": [
        "name"
      ]
    }
  }
}

This page as Markdown · All docs in one file