households:upsert

Description: Create a household or update a single household by ID.

---

Request Schema

{
  "payload": {
    "id": 1, // When set, update existing record, else create new record
    "type": "households:upsert",
    "name": "Flintstone Family",
    "import_id": "F0001",
    "category": { "id": 1 }, // Existing household category, see payload specs for the appropriate category: household_categories:query
    "locale": "en",
 "data_consent": "accepted",
    "accepts_marketing": true,
    "note": "Lorem Ipsum\ndolor sit amet.",
    "forms": [
      { "id": 1, "data": { "key1": "value1", ... } } // See form:fill, `subject` key not required
    ],
    "people": [
      {
        "type": "people:upsert", // See people:upsert
        "first_name": "John",
        "last_name": "Doe",
        "dob": "1970-12-30",
        "forms": [
          { "id": 2, "data": { "key1": "value1", ... } } // See form:fill, `subject` key not required
     ],
        "collaboration": {
          "title": "Father",
          "main": false
        }
      }, // New record
      {
        "id": 1, // When set, update existing record, else create new record
        "type": "people:upsert", // See people:upsert
        "first_name": "Jane",
        "last_name": "Doe",
        "dob": "1974-07-12",
        "collaboration": {
          "title": "Mother",
          "main": true
        }
      } // Existing record
    ],
    "contact_informations": [
      {
        "label": "Home",
        "type": "PhoneNumber",
        "info": "123 1234",
        "main": true
      }, // New record
      {
        "id": 1,
        "type": "Email",
        "label": "Office",
        "info": "info@example.com",
        "main": false
      } // Existing record
    ],
   "addresses": [
      {
        "name": "Home", // Address label
        "street1": "259 Wellington St. W", // Number and street
        "street2": "Appt 1", // Appartment number, PO Box, etc...
        "city": "Toronto", // City name
        "zip": "M5V 3P9", // Postal code
        "region_code": "ON", // Province/State code - https://en.wikipedia.org/wiki/ISO_3166-2
        "country_code": "CA", // Country code - https://en.wikipedia.org/wiki/ISO_3166-2
        "main": true // Main address, only 1 per household
      }, // New record
      {
        "id": 1,
        "name": "Office",
        "main": false
      } // Existing record, same attributes as example above
    ]
  },
  "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.
name	String	Yes	null	255	Household name. Required. Whitespace is trimmed.
import_id	String	Yes	Auto-generated	255	Your external system ID for this household. Unique per account. Auto-generated if not provided.
category	Object	No	null	-	{ "id": 1 }. See household_categories:query
locale	Enum	No	null	-	Values: fr, en
data_consent	Enum	No	unknown	-	Values: unknown, accepted, rejected
accepts_marketing	Boolean	No	false	-	Consent to receive electronic communications
reason	String	Conditional	null	255	Required when status is inactive
status	Enum	No	active	-	Values: wizard, active, inactive
note	Text	No	null	-	Free-form text about the household
federation_permission	Enum	No	confidential	-	Values: confidential, shared_with_subscribers
people	Array	No	[]	-	People to add to this household. See People fields
contact_informations	Array	No	[]	-	See ContactInformation fields
addresses	Array	No	[]	-	See Address fields

Special Field: import_id

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

Characteristics:

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

Nested People Fields

Each person object in the people array follows the people:upsert structure with an additional collaboration field:

Field	Type	Required	Description
type	String	Yes	Must be "people:upsert"
id	Integer	No	Arkipel person ID (for updating existing)
first_name	String	Conditional	See people:upsert
last_name	String	Conditional	See people:upsert
import_id	String	Yes	See people:upsert
collaboration	Object	No	Relationship details
collaboration.title	String	No	Role in household (e.g., “Father”, “Mother”)
collaboration.main	Boolean	No	Is this the primary contact? Default: false

Note: All other person fields from people:upsert are supported (gender, dob, contact_informations, addresses, etc.).

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": "households:upsert"
  }
}