notes:upsert

Description: Create a note or update a single note by ID or import_id.

Notes are attached to a subject (organization, household, or person) and can be used to store rich text content with a title.

When no subject is provided, the note is automatically attached to the current person identified by the incoming Arkipel message (the sender). If the sender has no person record in the target account, the note falls back to the account’s main organization.

---

Request Schema

{
  "payload": {
    "id": 1, // When set, update existing record, else create new record
    "import_id": "NOTE-001", // When set, update existing record, else create new record
    "type": "notes:upsert",
    "title": "Meeting Notes - Project Kickoff",
    "body": "<p>Discussed timeline and deliverables with the team.</p>",
    "subject": {
      "type": "organizations:upsert", // See payload specs for the appropriate subject type: organizations:upsert, households:upsert, people:upsert
      "id": 456,
      "import_id": "ORG-001",
      "name": "Toucan Solutions"
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

• See global request attributes

Field Constraints

Field	Type	Required	Default	Max Length	Constraints
id	Integer	No	null	-	Arkipel ID. When set, updates existing record. When omitted, creates new record.
import_id	String	Yes	Auto-generated	255	Your external system ID for this note. Unique per account. Auto-generated if not provided.
title	String	Yes	null	255	Note title. Required.
body	HTML	No	null	-	Note content. See HTML Content Guide
subject	Object	No	Sender’s person / Main org	-	What this note is attached to. When omitted, defaults to the sender’s person (falls back to the account’s main organization if sender has no person). See Subject fields

Special Field: import_id

The import_id field is your integration’s identifier for this note. Use it to link Arkipel records with your external system.

Characteristics:

• Required but auto-generated if not provided
• Must be unique per account
• Your external system ID format is recommended (e.g., note_123, log_456, comment_789)
• Used for idempotent operations and duplicate prevention
• Auto-generated format: 6 characters from 234679ACDEFGHJKMNPRTVWXYZ

Subject Fields

The subject is the entity this note is attached to (person, household, or organization). Optional — when omitted, the note attaches to the sender’s person.

Field	Type	Required	Description
type	String	Yes	Subject type: "organizations:upsert", "households:upsert", or "people:upsert"
id	Integer	Conditional	Arkipel subject ID (to attach to existing subject)
import_id	String	Conditional	Your external system ID for the subject
name	String	Conditional	Required when creating a new organization/household subject
first_name	String	Conditional	Required when creating a new person subject
last_name	String	Conditional	Required when creating a new person subject

Subject lookup/creation logic:

1. If id is provided → attaches to existing Arkipel subject
2. If import_id is provided → looks up by your external ID, creates if not found
3. If neither provided with minimal fields → creates new subject
4. If subject is entirely omitted → attaches to the current person (the sender), or falls back to the account’s main organization if the sender has no person record

Real Life Example

Creating a Note on an Existing Organization

{
  "type": "notes:upsert",
  "title": "Follow-up Required",
  "body": "<p>Customer requested callback next week regarding their inquiry.</p>",
  "subject": {
    "type": "organizations:upsert",
    "id": 260926
  }
}

Creating a Note with a New Household Subject

{
  "type": "notes:upsert",
  "import_id": "NOTE-2024-001",
  "title": "Initial Contact",
  "body": "<p>First meeting completed. Family interested in services.</p>",
  "subject": {
    "type": "households:upsert",
    "name": "Smith Family",
    "import_id": "HOUSE-001",
    "locale": "en"
  }
}

Quick Note Creation (No Subject)

When no subject is provided, the note is automatically attached to the current person (the sender identified by the incoming message). If the sender has no person record in the target account, the note falls back to the account’s main organization.

{
  "type": "notes:upsert",
  "title": "Thoughts of the day",
  "body": "<p>Quick personal reflection without attaching to a specific entity.</p>"
}

Updating an Existing Note by Import ID

{
  "type": "notes:upsert",
  "import_id": "NOTE-2024-001",
  "title": "Updated Meeting Notes",
  "body": "<p>Follow-up completed. Services accepted.</p>"
}

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "http",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-11-13T20:52:49Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "message_id": "6916452112f746b2b4cf48c1",
    "type": "notes:upsert"
  }
}