recipient

A recipient is someone goods go to. There are three kinds:

kind	Delivery notes	Loans	Meaning
customer	yes	yes (external borrower)	A company or person outside the organisation
site	yes	yes (external borrower)	A construction site or project location
employee	no	yes	A member of staff who borrows equipment

• Mutable: the version with the greater hlc wins.
• Ids: random UUIDs.
• Delivery notes and loans copy the recipient's name and address at the time of issue, so later edits do not change issued documents.

Fields

Field	Type	Writer	Default	Meaning
kind	string?	optional	customer	customer, site or employee. Readers treat unknown values as customer.
name	string	server		Company, site or person
number	string?	optional	none	Customer number, or personnel number for employees
department	string?	optional	none	Employees only: department or team
street	string?	optional	none
postal_code	string?	optional	none
city	string?	optional	none
country	string?	optional	none	Free text, as printed
contact	string?	optional	none	Contact person
phone	string?	optional	none
email	string?	optional	none	Copied to loans, where the protocols can be sent
erp_reference	string?	optional	none	Key of the recipient in another system
archived	boolean?	optional	false	Hidden from lists and pickers
created_at	date-time?	optional	none	When the first device created the record; display only

Rules for writers

• name is trimmed and must not be empty.
• The reference app writes department only for employees and clears it for other kinds.
• The reference app neither deletes nor archives recipients. It hides recipients that another writer (an ERP import, for example) archived, and still shows them on existing documents.

Server validation

Field	Rules
name	required, string
kind	nullable, one of customer, site, employee
department, number, street, postal_code, city, country, contact, phone, email, erp_reference	nullable, string
archived	nullable, boolean

Examples

{
  "entity": "recipient",
  "id": "5E2A8C14-9D3B-4A7F-B6C0-1E4D7F2A9B35",
  "op": "upsert",
  "hlc": "001791792000123-0003-3F2A9C1B",
  "data": {
    "kind": "site",
    "name": "Northring construction site",
    "number": "K-10042",
    "street": "Northring 12",
    "postal_code": "10115",
    "city": "Berlin",
    "country": "Germany",
    "contact": "Max Mustermann",
    "phone": "+49 30 1234567",
    "created_at": "2026-10-12T08:00:00Z"
  }
}

{
  "entity": "recipient",
  "id": "3C9E5A72-4B1D-4E8A-9F26-0A7B3C5D8E14",
  "op": "upsert",
  "hlc": "001791792000123-0004-3F2A9C1B",
  "data": { "kind": "employee", "name": "Erika Mustermann", "number": "P-0815", "department": "Service", "email": "[email protected]" }
}

Schema

schemas/recipient.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Recipient",
  "description": "Customer, construction site or employee. Customers and sites receive goods on delivery notes; all three kinds can borrow equipment on loans, employees only on loans. Mutable: the version with the greater hlc wins.",
  "type": "object",
  "required": ["name"],
  "properties": {
    "kind": { "description": "Absent or null means \"customer\".", "type": ["string", "null"], "enum": ["customer", "site", "employee", null], "default": "customer" },
    "name": { "description": "Name of the company, site or person.", "type": "string", "minLength": 1 },
    "number": { "description": "Customer number, or personnel number for employees.", "type": ["string", "null"] },
    "department": { "description": "Employees only: department or team.", "type": ["string", "null"] },
    "street": { "type": ["string", "null"] },
    "postal_code": { "type": ["string", "null"] },
    "city": { "type": ["string", "null"] },
    "country": { "description": "Free text, as printed.", "type": ["string", "null"] },
    "contact": { "description": "Contact person.", "type": ["string", "null"] },
    "phone": { "type": ["string", "null"] },
    "email": { "type": ["string", "null"] },
    "erp_reference": { "description": "Key of the recipient in another system.", "type": ["string", "null"] },
    "archived": { "description": "Hidden from lists and pickers. Absent or null means false.", "type": ["boolean", "null"] },
    "created_at": { "description": "When the record was first created, set once by the creating device. Display only.", "type": ["string", "null"], "format": "date-time" }
  },
  "additionalProperties": true,
  "examples": [
    {
      "kind": "site",
      "name": "Northring construction site",
      "number": "K-10042",
      "street": "Northring 12",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "Germany",
      "contact": "Max Mustermann",
      "phone": "+49 30 1234567",
      "created_at": "2026-10-12T08:00:00Z"
    },
    {
      "kind": "employee",
      "name": "Erika Mustermann",
      "number": "P-0815",
      "department": "Service",
      "email": "[email protected]"
    }
  ]
}