people:upsert

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

---

Request Schema

{
  "payload": {
    "id": 1, // When set, update existing record, else create new record
    "type": "people:upsert",
    "first_name": "Jane",
    "last_name": "Doe",
    "import_id": "JD0001",
    "category": { "id": 1 }, // Existing person category, see payload specs for the appropriate category: person_categories:query
    "locale": "fr",
    "gender": "woman",
    "dob": "1970-12-30",
    "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
    ],
    "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 person
      }, // 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
• payload.id - Integer - The person’s ID in the remote Arkipel community - when not set, a record will be created
• payload.first_name - String - The person’s first name - Compulsory if last_name blank
• payload.last_name - String - The person’s last name - Compulsory if first_name blank
• payload.import_id - String - External person reference - Compulsory and unique, auto-generated if blank

Additional values

• payload.category - Hash[id] - The person’s category - See Message person_categories:query
• payload.locale - Enum (fr, en) - The person’s preferred language
• payload.gender - Enum (unknown (default), confidential, man, woman, other) - The person’s gender
• payload.dob - Date (format: "%Y-%M-%d") - The person’s date of birth
• payload.data_consent - Enum (unknown (default), accepted, rejected) - The person’s data content status
• payload.accepts_marketing - Boolean (false (default), true) - The person’s consent to receiving electronic communications
• payload.note - Text - Text note about the person
• payload.contact_informations - Array[id, label , type , info, main] - The person’s contact informations (if id nil: mutation=create, if id present: mutation=update)
• payload.addresses - Array[id, name , street1 , street2, city, zip, region_code, country_code, main] - The person’s addresses (if id nil: mutation=create, if id present: mutation=update)

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