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.

---

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	Yes*	null	-	What this note is attached to. Required for creation. See Subject fields

* Required only when creating new note (when id and import_id are not set).

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):

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

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"
  }
}

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"
  }
}