Skip to content
Browse docsadd_notes

add_notes

Appends private notes for owned contacts or yourself. Each note is a complete observation with enough subject, timing, attribution and context to stand alone. Corrections and explicit requests to forget a claim are new notes explaining what should change in the maintained profile. Original records remain.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Inputs#

InputRequiredDescription
notesyes1–24 objects with personId (an owned person UUID, or null for self), text, nullable scope, nullable uncertainty, and reason.
requestIdyesA fresh UUID for a new batch. Reuse the same ID and identical notes to retry an uncertain save.

Text allows 1–4,000 characters, scope and uncertainty each allow 1–500 characters or null, and reason allows 1–1,000 characters. The full batch commits atomically. An invalid or unowned subject rejects all notes. Reusing a request ID with different content or a different batch size rejects the request.

Returns and processing#

Success is { status: "success", outcome, message, notes }. The batch outcome is saved or no_change; each note includes its identity, subject, full content, creation time and outcome (added or already_saved). An identical retry preserves the original note and its processing state. Separate new observations use new request IDs, even if their text is identical.

Combine considers each pending note once. Successful processing, including a deliberate decision not to change the profile, closes the note's Undo window. Failed processing leaves it pending. Where the interface offers a receipt's Undo, it withdraws only a still-pending note. Notes cannot be rewritten or deleted through statement-edit tools. No search or outreach starts from this save.

Example#

json
{
  "requestId": "00000000-0000-4000-a000-000000000090",
  "notes": [
    {
      "personId": "00000000-0000-4000-a000-000000000005",
      "text": "Pat prefers a short introduction with the project context before scheduling a call.",
      "scope": null,
      "uncertainty": null,
      "reason": "The member explained Pat's communication preference."
    }
  ]
}

Result (synthetic data):

json
{
  "status": "success",
  "outcome": "saved",
  "message": "The private notes were saved.",
  "notes": [
    {
      "id": "00000000-0000-4000-a000-000000000091",
      "personId": "00000000-0000-4000-a000-000000000005",
      "text": "Pat prefers a short introduction with the project context before scheduling a call.",
      "scope": null,
      "uncertainty": null,
      "createdAt": "2026-10-31T12:00:00.000Z",
      "outcome": "added"
    }
  ]
}

See get_person, get_self_profile, and the private notes workflow.