Skip to content

Latest commit

 

History

History
900 lines (772 loc) · 70.9 KB

letting_context.md

File metadata and controls

900 lines (772 loc) · 70.9 KB

Letting Context

Events

Type GARAIO REM REM Description
Letting.Tenancy.Created ✅ ❌ A tenancy has been created; does not reliably signal a tenant move in. (1)
Letting.Tenancy.Updated ✅ ❌ Start and / or end date of a tenancy have been changed
Letting.Tenancy.Deleted ✅ ❌ A tenancy has been deleted; this means that the tenancy never became effective
Letting.Tenancy.TenancyAgreementReferenceChanged ✅ ❌ The reference of a tenancy agreement has changed
Letting.Reservation.Update ✅ ❌ Updates the reservation status of a unit.
Letting.TenancyAgreement.Create ✅ ❌ A tenancy agreement should be created in GARAIO REM
Letting.TenancyAgreement.Activate ✅ ❌ A tenancy agreement should be activated in GARAIO REM
Letting.TenancyAgreement.Delete ✅ ❌ A tenancy agreement should be deleted in GARAIO REM
Letting.TenancyAgreementSecurityDepot.Update ✅ ❌ Updates the reservation status of a unit.
Letting.TenancyAgreementDetails.Update ✅ ❌ Updates some details of a tenancy agreement.
Letting.Tenancy.MoveInConfirmed ❌ ✅ Confirms a tenant will move or has moved into a unit. (2)
Letting.Tenancy.MoveOutConfirmed ❌ ✅ Confirms a tenant will move out or has moved out of a unit. (3)
Letting.Tenant.Updated ✅ ❌ Notification when tenant information has been updated/changed

Notes

  • (1) A tenancy is uniquely identified by tenancy agreement reference, tenant reference and unit reference
  • (2) This event is only raised for tenants that live or trade in a given unit. For example the event is not raised for tenants that act as guarantors or for tenants that have had their tenancy agreement changed while staying in the same unit.
  • (3) Like Letting.Tenancy.MoveInConfirmed the event is also only raised when a tenant has lived or traded in person at the given unit.

Letting.Tenancy.Created

NOTE: We have discoved minor differences in the logic for sending the preferred email and phoneNumber in mbus messages, the priority is always the same for all persons, while GraphQL queries send different values Legal and Physical persons. At the moment, we are not planning to change this behaviour without consulting our partners, in order to prevent unexpected side effects.

Field Type Content / Remarks
eventType string Letting.Tenancy.Created
data hash
  startDate string ISO 8601 encoded date, eg '2019-05-25'
  endDate string ISO 8601 encoded date, eg '2019-05-25'; might be null
  tenancyAgreementReference string unique tenancy agreement identifier, eg '1234.01.0001.01'
  unitReference string unique unit identifier, eg '234.01.0001'
  tenant hash
    reference string tenant reference; uniquely identifies a person
    firstName string
    surname string
    languageCode string de, fr, it or en; must be lower case
    nationalityCode string ISO country code (ISO 3166-1 alpha-2), eg 'CH'
    phoneNumber string might be null
    email string might be null
    fullName string built from the individual name parts, respecting the type of tenant (corporate or physical)
    type string LEGAL (a company) or PHYSICAL (Physical person)
    dateOfBirth string ISO 8601 encoded date, eg '2019-05-30'
    allphoneNumbers array of hashes a list of all available email addresses and type
     phoneNumber string
     type string one of: PRIVATE, PROFESSIONAL, MOBILE or OTHER
    allEmails array of hashes a list of all available email addresses and type
     emailAddress string
     type string one of: PRIVATE, PROFESSIONAL or OTHER
    postalAddress hash current address fields conformant to the eCH-0010 specs
     addressLine1 string See eCH-0010 specs
     countryCode string ISO 3166-1 alpha-2 country code, eg CH
     city string
     zipCode string
     postOfficeBoxText string See eCH-0010 specs
     street string Street name including number where appropriate

Example

{"eventType":"Letting.Tenancy.Created",
  "data":{
    "startDate":"2019-05-01",
    "endDate":null,
    "tenancyAgreementReference":"10001.786.29.01",
    "unitReference":"10001.786.29",
    "tenant":{
      "reference":"100004",
      "firstName":"Haupt",
      "surname":"Mieter",
      "languageCode":"de",
      "nationalityCode":"AT",
      "phoneNumber":"+41 31 331 21 11",
      "email":"[email protected]",
      "fullName":"Haupt Mieter",
      "type":"PHYSICAL",
      "dateOfBirth":"1980-01-01",
      "allphoneNumbers":[
        {"phoneNumber":"+41 31 331 21 11","type":"PRIVATE"},
        {"phoneNumber":"+41 31 331 21 12","type":"PROFESSIONAL"},
        {"phoneNumber":"+41 31 331 21 13","type":"MOBILE"},
        {"phoneNumber":"+41 31 331 21 14","type":"OTHER"}
      ],
      "allEmails":[
        {"emailAddress":"[email protected]","type":"PRIVATE"},
        {"emailAddress":"[email protected]","type":"PROFESSIONAL"}
      ],
      "postalAddress":{
        "addressLine1":"Haupt Mieter",
        "countryCode":"CH",
        "city":"Bern",
        "zipCode":"3000",
        "postOfficeBoxText":"Postfach 1234",
        "street":"Hauptstrasse 1"
      }
    }
  }
}

Letting.Tenancy.Updated

Field Type Content / Remarks
eventType string Letting.Tenancy.Updated
data hash
  startDate string ISO 8601 encoded date, eg '2019-05-25'
  endDate string ISO 8601 encoded date, eg '2019-05-25'; might be null
  tenancyAgreementReference string unique tenancy agreement identifier, eg '1234.01.0001.01'
  unitReference string unique unit identifier, eg '234.01.0001'
  tenantReference string unique person identifier, eg '1234'

Example

{"eventType":"Letting.Tenancy.Updated",
  "data":{
    "startDate":"2019-05-01",
    "endDate":null,
    "tenancyAgreementReference":"10001.786.29.01",
    "unitReference":"10001.786.29",
    "tenantReference":"100004"
    }
  }
}

Letting.Tenancy.Deleted

Field Type Content / Remarks
eventType string Letting.Tenancy.Deleted
data hash
  tenancyAgreementReference string unique tenancy agreement identifier, eg '1234.01.0001.01'
  unitReference string unique unit identifier, eg '234.01.0001'
  tenantReference string unique person identifier, eg '1234'

Example

{"eventType":"Letting.Tenancy.Deleted",
  "data":{
    "tenancyAgreementReference":"10001.786.29.01",
    "unitReference":"10001.786.29",
    "tenantReference":"100004"
  }
}

Letting.Tenancy.TenancyAgreementReferenceChanged

A user might change the reference of a unit in GARAIO REM which affects tenancy agreement references as well. This event reflects such a change. If you store tenancy data in a local domain model you must apply this change to your data.

Field Type Content / Remarks
eventType string Letting.Tenancy.TenancyAgreementReferenceChanged
data hash
  tenancyAgreementReference string unique tenancy agreement identifier, eg '1234.01.0001.01'
  newTenancyAgreementReference string new identifier for the tenancy agreement, eg '1234.01.0011.01'

Example

{"eventType":"Letting.Tenancy.TenancyAgreementReferenceChanged",
  "data":{
    "tenancyAgreementReference":"1234.01.0001.01",
    "newTenancyAgreementReference":"1234.01.0011.01",
  }
}

Letting.Tenancy.MoveInConfirmed

Field Type Content / Remarks
eventType string Letting.Tenancy.MoveInConfirmed
data hash
  tenancyStartDate string ISO 8601 encoded date, eg '2019-03-01'
  tenancyAgreementReference string unique tenancy agreement identifier, eg '1234.01.0001.01'
  unitReference string unique unit identifier, eg '234.01.0001'
  tenant hash
    reference string tenant reference; uniquely identifies a person
    previousAddress hash the address where the tenant lived or traded before. Can be nil if unknown.
      street string street name including the building number where appropriate
      zipCode string
      city string
      countryCode string ISO country code, eg 'CH'
  lettingContactReference string person reference. (1)

Notes

  • (1) uniquely identifies the management team member who represents the property owner regarding this tenancy.

Additional Header Properties

local_authority

Example

{
  "eventType": "Letting.Tenancy.MoveInConfirmed",
  "data": {
    "tenancyStartDate": "2019-01-01",
    "tenancyAgreementReference": "6020.03.0001.07",
    "unitReference": "6020.02.0101",
    "tenant": {
      "reference": "9913",
      "previousAddress": {
        "street": "Huobmatt 7a",
        "zipCode": "4005",
        "city": "Olten",
        "countryCode": "CH"
      }
    },
    "lettingContactReference": "ruf134",
    "isTest": null
  }
}

Letting.Tenancy.MoveOutConfirmed

Field Type Content / Remarks
eventType string Letting.Tenancy.MoveOutConfirmed
data hash
  tenancyEndDate string ISO 8601 encoded date, eg '2019-05-30'
  tenancyAgreementReference string unique tenancy agreement identifier, eg '1234.01.0001.01'
  unitReference string unique unit identifier, eg '234.01.0001'
  tenant hash
    reference string tenant reference; uniquely identifies a person
    nextAddress hash the address where the tenant will live or trade next. Can be nil if unknown.
      street string street name including the building number where appropriate
      zipCode string
      city string
      countryCode string ISO country code, eg 'CH'
  lettingContactReference string person reference. (1)

Notes

  • (1) uniquely identifies the management team member who represents the property owner regarding this tenancy.

Additional Header Properties

local_authority

Example

TODO

Letting.Reservation.Update

Field Type Content / Remarks
eventType string Letting.Reservation.Update
data hash
  unitReference string unique unit identifier, eg '234.01.0001'; required
  reserve boolean reserve the unit if true, free the unit if false; required
  reservedForPersonReference string person the unit is reserved for. reference; uniquely identifies a person. (1)
  reservationTypeCode string reservation type code ("Objektreservierungsart"). (1)
  reservationReason string reservation reason. (1)

Notes:

  • (1) If reserve is set to false, you must not use this field.

Example

{
  "eventType":"Letting.Reservation.Update",
  "data": {
    "reserve": true,
    "unitReference": "10001.353.423",
    "reservationTypeCode": "01",
    "reservedForPersonReference": "100004",
    "reservationReason": "reason"
  }
}

Letting.Reservation.UpdateAccepted

The Accept message.

Additional data fields:

Field Type Content / Remarks
unitReference string The unit reference given in the request message

Letting.Reservation.UpdateRejected

The Reject message.

Additional data fields:

Field Type Content / Remarks
unitReference string The unit reference given in the request message

Letting.TenancyAgreement.Create

This message is sent from an external message publisher to a GARAIO REM instance and allows to create a tenancy agreement. Set the recipient property in the headers, eg "grem_wincasa". Always required attributes are noted in the remarks. Depending on the tenancy agreement template configuration, additional attributes may be required.

GARAIO REM replies with a standard Accepted / Rejected message containing the tenancyAgreementReference, VAT state infos and rental costs of the created tenancy agreement or reject reasons

Field Type Content / Remarks
eventType string Letting.TenancyAgreement.Create
data hash
  primaryUnitReference string reference of an available unit; required
  tenancyAgreementTypeCode string a valid tenancy agreement type code (see code table entries (mietvertrag_typ) for valid codes); required
  rentStartDate string ISO 8601 encoded date, eg '2019-03-01'; required
  contractDate string ISO 8601 encoded date, eg '2019-02-18'; required
  paymentModeCode string a valid code from the zahlmodus code table; defaults to '01' (monthly in advance)
  primaryTenant hash data describing the primary tenant; a new tenant will be created if no tenant with the same name and dateOfBirth exists; required
    firstName string first name; required
    surname string surname; required
    address hash current address
      city string city; required
      zipCode string zipCode; required
      street string street incl. number; required
      countryCode string ISO country code, eg 'CH'; required
    correspondenceLanguageCode string de, fr, it or en; must be lower case, required
    tenantIndustryCode string a valid rental type code (see code table entries (branche_mieter) for valid codes)
    email string email address
    phoneNumber string phone number (international format)
    maritalStatus string one of the following values will be accepted: unmarried, married, widowed, divorced, separated, civil_union. Send either maritalStatus or maritalStatusCode but not both.
    maritalStatusCode string a value of the marital status code table (see code table entries "Zivilstände" for valid codes). Send either maritalStatus or maritalStatusCode but not both.
    dateOfBirth string ISO 8601 encoded date, eg '2019-03-01'; required
    homeTown string home town
    nationalityCode string ISO country code, eg 'CH'
    jobTitle string job title
    salutation string one of the following values will be accepted: none, sir, madam. Send either salutation or salutationCode but not both.
    salutationCode string a value of the salutation code table (see code table entries "Anreden" for valid codes). Send either salutation or salutationCode but not both.
    iban string a valid IBAN for payouts
    bic string a valid BIC (Bank Identification Code) for payouts. For CH and LI IBANs, this field must be omitted or set to null. For other country IBANs, this field is required.
    assignBuildingAddress boolean should the building address be assigned per rent start date?
    isResident boolean does the person live here? defaults to false.
  jointTenants array data describing optional joint tenants; new tenants will be created if no tenant with the same name and dateOfBirth exists
    firstName string first name; required
    surname string surname; required
    address hash current address
      city string city; required
      zipCode string zipCode; required
      street string street incl. number; required
      countryCode string ISO country code, eg 'CH'; required
    correspondenceLanguageCode string de, fr, it or en; must be lower case, required
    email string email address
    phoneNumber string phone number (international format)
    maritalStatus string one of the following values will be accepted: unmarried, married, widowed, divorced, separated, civil_union. Send either maritalStatus or maritalStatusCode but not both.
    maritalStatusCode string a value of the marital status code table (see code table entries "Zivilstände" for valid codes). Send either maritalStatus or maritalStatusCode but not both.
    dateOfBirth string ISO 8601 encoded date, eg '2019-03-01'; required
    homeTown string home town
    nationalityCode string ISO country code, eg 'CH'
    jobTitle string job title
    salutation string one of the following values will be accepted: none, sir, madam. Send either salutation or salutationCode but not both.
    salutationCode string a value of the salutation code table (see code table entries "Anreden" for valid codes). Send either salutation or salutationCode but not both.
    assignBuildingAddress boolean should the building address be assigned per rent start date?
    isResident boolean does the person live here? defaults to false.
  rentRegulations hash optional rent regulations
    rentalTypeCode string a valid rental type code (see code table entries (mieter_art) for valid codes); required
    rentLockedUntil string ISO 8601 encoded date, eg '2019-03-01'
    rentLockedReason string reason why the rent is locked
  limitedUntil string optional ISO 8601 encoded date, eg '2019-03-31'; if applied, valid cancellationRegulations must be applied, too
  cancellationRegulations hash cancellation regulations
    cancellationModeCode string a valid cancellation mode code (see code table entries (kuendigungs_termin) for valid codes)
    cancellationPeriodInMonths integer minimum number of months a cancellation must be announced in advance by the landlord
    cancellationPeriodTenantInMonths integer minimum number of months a cancellation must be announced in advance by the tenant
    earliestPossibleTerminationDateLandlord string ISO 8601 encoded date, eg '2019-03-01'
    earliestPossibleTerminationDatesTenant string ISO 8601 encoded date, eg '2019-03-01'
  securityDeposit hash security deposit
    depositTypeCode string a valid deposit type code (see code table entries (depot_art) for valid codes)
    depositAmount decimal amount to pay in CHF
    paidAmount decimal paid amount in CHF
    bankGuaranteeExpiration string ISO 8601 encoded date, eg '2023-12-31'
    refundedAt string ISO 8601 encoded date, eg '2024-12-31'
    depositAccountNumber string payment information. freetext, use e.g. for IBAN
    custodianReference string person reference of the custodian
    payerReference string person reference of the payer
  intendedUse hash intended use
    numberOfPeople integer number of people
    installationsForCommonUsage string freetext describing installations for common usage
    roomsForSoleUsage array rooms for sole usage
      unitTypeCode string a valid unit type code (see code table entries (objekt_art) for valid codes)
      number string unit number
  initialRentForm hash initial rent form data
    reason string Reason for the rent
    withSupportContribution boolean has the tenancy agreement support contribution?

Examples

minimal required attributes
{"eventType":"Letting.TenancyAgreement.Create",
  "data":{
    "primaryUnitReference":"1234.01.0001",
    "tenancyAgreementTypeCode":"1",
    "rentStartDate":"2023-06-01",
    "contractDate":"2023-05-15",
    "paymentModeCode":"03",
    "primaryTenant":{
      "firstName":"Max",
      "surname":"Muster",
      "address":{
        "street":"Bahnhofstrasse 23",
        "zipCode":"3000",
        "city":"Bern",
        "countryCode":"CH",
      },
      "correspondenceLanguageCode":"de",
      "dateOfBirth":"1972-11-23"
    }
  }
}
all available attributes
{"eventType":"Letting.TenancyAgreement.Create",
  "data":{
    "primaryUnitReference":"1234.01.0001",
    "tenancyAgreementTypeCode":"1",
    "rentStartDate":"2023-06-01",
    "primaryTenant":{
      "firstName":"Max",
      "surname":"Muster",
      "address":{
        "street":"Bahnhofstrasse 23",
        "zipCode":"3000",
        "city":"Bern",
        "countryCode":"CH",
      },
      "tenantIndustryCode":"01",
      "correspondenceLanguageCode":"de",
      "dateOfBirth":"1972-11-23",
      "email":"[email protected]",
      "phoneNumber":"+41 123 45 67",
      "maritalStatus":"civil_union",
      "homeTown":"Bern",
      "nationalityCode":"AT",
      "jobTitle":"software engineer",
      "salutation":"sir",
      "iban":"CH9531999000000001234",
      "assignBuildingAddress": true
    },
    "jointTenants":[
      {
        "firstName":"Jeanine",
        "surname":"Gibtsnicht",
        "address":{
          "street":"Freiestrasse 2a",
          "zipCode":"5000",
          "city":"Aarau",
          "countryCode":"CH",
        },
        "correspondenceLanguageCode":"de",
        "dateOfBirth":"1981-03-12",
        "email":"[email protected]",
        "phoneNumber":"+41 765 43 21",
        "maritalStatus":"civil_union",
        "homeTown":"Aarau",
        "nationalityCode":"DE",
        "jobTitle":"Medizinische Praxisassistentin",
        "salutation":"madam",
        "assignBuildingAddress": false
      }
    ],
    "cancellationRegulations":{
      "cancellationModeCode":"01",
      "cancellationPeriodInMonths":3,
      "cancellationPeriodTenantInMonths":3,
      "earliestPossibleTerminationDateLandlord":"2023-12-31",
      "earliestPossibleTerminationDatesTenant":"2023-12-31"
    },
    "securityDeposit":{
      "depositTypeCode":"01",
      "depositAmount":5000.00,
      "paidAmount":5000.00,
      "depositAccountNumber":"DE21700500000003600282",
      "custodianReference":"123456",
      "payerReference":"654321"
    },
    "intendedUse":{
      "numberOfPeople":2,
      "installationsForCommonUsage":"Veloraum",
      "roomsForSoleUsage":[
        {
          "unitTypeCode":"26",
          "number":"1234"
        }
      ]
    },
    "initialRentForm": {
      "reason":"Erstvermietung",
      "withSupportContribution":false,
    }
  }
}
accepted response message
Field Type Content / Remarks
tenancyAgreementReference string The generated tenancy agreement reference
vat hash VAT (MWSt) info
  validFrom string ISO 8601 encoded date, eg '2023-06-01'
  liable boolean Is the tenancy agreement VAT liable?
  code string VAT code (see MWST code table)
  rate decimal VAT rate
  primaryTenancyAgreementReference string reference of the primary tenancy agreement (if applicable)
rentalCosts hash rental costs info
  netRent decimal net rent in CHF
  grossRentExcludingVat decimal gross rent without vat in CHF
  additionalCosts decimal additional costs in CHF
  additionalCostsComponents array additional costs components (code, amount, see Mietzinskomponente-Typen code table)
rentReserves hash Rent reserves ("Mietzinsreserven")
  fromRentBasePercent decimal "Aufgrund Mietzinsbasis", in Percent
  fromRentBaseAmount decimal "Aufgrund Mietzinsbasis", in CHF
  mortgageRateAdjustment decimal "Hypozinsanpassung", in Percent
  countryIndexAdjustment decimal "Landesindexanpassung", in Percent
  costIncreaseAdjustment decimal "Kostensteigerungsanpassung", in Percent
  fromInsufficientReturnPercent decimal "aufgrund ungenügender Bruttorendite", in Percent
  fromInsufficientReturnAmount decimal "aufgrund ungenügender Bruttorendite", in CHF
  fromLocalStandardsPercent decimal "aufgrund Orts- und Quartierüblichkeit", in Percent
  fromLocalStandardsAmount decimal "aufgrund Orts- und Quartierüblichkeit", in CHF
  fromValueAddingInvestmentsPercent decimal "aufgrund wertvermehrender Investitionen", in Percent
  fromValueAddingInvestmentsAmount decimal "aufgrund wertvermehrender Investitionen", in CHF
  fromValueAddingInvestmentsPotentials array Array of hashes (typeCode, amount, notes, see Mietzinsreserven code table)
  fromValueAddingInvestmentsTable array Array of hashes (title, percent, amount) 
{"eventType":"Letting.TenancyAgreement.CreateAccepted",
  "data":{
    "tenancyAgreementReference":"1234.01.0001.02",
    "vat":{
      "validFrom":"2023-06-01",
      "liable":false,
      "code":"NO",
      "rate":7.7,
      "primaryTenancyAgreementReference":null
    },
    "rentalCosts":{
      "netRent":2000.0,
      "grossRentExcludingVat": 2010.0,
      "additionalCosts":10.0,
      "additionalCostsComponents":[
        {"code":"10",
        "amount":10.0}
      ]
    },
    "rentalBasis":{
      "mortageRate":2.75,
      "mortageRateDate":"2005-01-01",
      "costIncreaseDate":"",
      "countryIndexDate":"",
      "countryIndexBaseYear":null,
      "countryIndexPoints":null
    },
    "paymentModeCode":"01",
    "rentReserves": {
      "fromRentBasePercent":8.24,
      "fromRentBaseAmount":62.698,
      "mortgageRateAdjustment":6.0,
      "countryIndexAdjustment":2.42,
      "costIncreaseAdjustment":0.0,
      "fromInsufficientReturnPercent":1.1,
      "fromInsufficientReturnAmount":1000.0,
      "fromLocalStandardsPercent":1.2,
      "fromLocalStandardsAmount":2000.0,
      "fromValueAddingInvestmentsPercent":1.3,
      "fromValueAddingInvestmentsAmount":3000.0,
      "fromValueAddingInvestmentsPotentials":[
        { "typeCode":"30",
          "amount":300.0
          "notes":null}
      ],
      "fromValueAddingInvestmentsTable":[
        { "title":"Mietzins-Reserve aufgrund wertvermehrender Investitionen",
          "percent": "5.9%",
          "amount": "44.00"}
      ]
    }
  }
}
rejected response message
{"eventType":"Letting.TenancyAgreement.CreateRejected",
  "data":{
    "reasons":[
      {
        "attribute":"primaryTenant.correspondenceLanguageCode",
        "reason":"darf nicht leer sein"
      },
      {
        "attribute":"primaryTenant.surname",
        "reason":"darf nicht leer sein"
      }
    ]
  }
}

Letting.TenancyAgreement.Activate

Activate a tenancy agreement in GREM.

Field Type Content / Remarks
eventType string Letting.TenancyAgreement.Activate
data hash
  reference string tenancy agreement reference; required

Letting.TenancyAgreement.ActivateAccepted

The Accept message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.TenancyAgreement.ActivateRejected

The Reject message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.TenancyAgreement.Delete

Delete requests for activated tenancy agreements will be rejected (only agreements in states in_erfassung and validiert are deletable).

Field Type Content / Remarks
eventType string Letting.TenancyAgreement.Delete
data hash
  reference string tenancy agreement reference; required

Letting.TenancyAgreement.DeleteAccepted

The Accept message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.TenancyAgreement.DeleteRejected

The Reject message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.TenancyAgreementSecurityDepot.Update

Field Type Content / Remarks
eventType string Letting.TenancyAgreementSecurityDepot.Update
data hash
  reference string tenancy agreement reference; required
  depositTypeCode string deposit type code ("Depot-Art"); required
  custodianReference string person that is the custodian for the depot; reference (1)
  payerReference string person that pays the depot; reference (1)
  depositAmount decimal amount to pay in CHF (1)
  paidAmount decimal paid amount in CHF (1)
  depositAccountNumber string payment information. freetext, use e.g. for IBAN (1)
  refundedAt string ISO 8601 encoded date, eg '2019-05-25'
  refundedByInfo string refunded by information, freetext

Notes:

  • (1) Whether the field is required depends on the configuration of your depositTypeCode.

Example

{
  "eventType":"Letting.TenancyAgreementSecurityDepot.Update",
  "data": {
    "reference":"10001.869.474.01",
    "depositTypeCode":"1",
    "custodianReference":"100006",
    "payerReference":"100007",
    "depositAmount":"10",
    "paidAmount":"0",
    "depositAccountNumber":"CH00 0000 0000 0000 0000 0",
    "refundedAt":"2019-05-25",
    "refundedByInfo":"some info"
  }
}

Letting.TenancyAgreementSecurityDepot.UpdateAccepted

The Accept message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.TenancyAgreementSecurityDepot.UpdateRejected

The Reject message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.TenancyAgreementDetails.Update

Field Type Content / Remarks
eventType string Letting.TenancyAgreementDetails.Update
data hash
  reference string tenancy agreement identifier, eg '234.01.0001'; required
  liabilityInsuranceChecked boolean whether the necessary liability insurance checks were done.

Example

{
  "eventType":"Letting.TenancyAgreementDetails.Update",
  "data": {
    "reference": "10001.349.769.01",
    "liabilityInsuranceChecked": true
  }
}

Letting.TenancyAgreementDetails.UpdateAccepted

The Accept message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.TenancyAgreementDetails.UpdateRejected

The Reject message.

Additional data fields:

Field Type Content / Remarks
reference string The tenancy agreement reference

Letting.Tenant.Updated

Letting.Tenant messages are sent when a tenant is updated or merged with another person.

These messages are sent for EACH Tenancy Agreement that the tenant is linked to and only sent to relevant parties. This is accomplished (on the backend), by including the property and unit so that we can check the associated Tags to filter for allowed message recipients.)

Because we send a message for each Tenancy, we also send the following fields: tenancyAgreementReference, unitReference, tenantReference to ensure a successful lookup on the remote system. tenant fields are optional and will generally only be sent if they have changed. The possible Tenant fields to be sent should be the same as those in the Letting.Tenant.Create message. (Please notify us if you find any discrepancies.)

  • When an address is added the full address data indluding a validFrom (in case it is an address for the future).
  • When an address is deleted the full current address data will be sent (it is possible that an older address was deleted and the address hasn't actually changed).
  • when an address is changed (updated) we will only send the address fields that have changed (and the validFrom date - incase it is a future address)
  • In the case of a removed email or phoneNumber, the corresponding preferred value will always be sent, as it is difficult to know if the preferred value has changed.
  • In the case of a tenant merge, the full tenant data will be sent, as it is difficult to know what has changed, since the old record has already been removed at the time of building this message. It is also important to note, that in the case of a merge the reference field will be changed and MUST be updated in order to match all future tenant references in ANY subsequent messages.

NOTE:

Field Type Content / Remarks
eventType string Letting.Tenant.Updated
data hash
  tenancyAgreementReference string unique tenancy agreement identifier, eg '1234.01.0001.01'
  unitReference string unique unit identifier, eg '234.01.0001'
  tenantReference string unique tenant identifier, eg '100004' - this is ALWAYS the reference previously published
  tenant hash ALL TENANT FIELDS except REFERENCE are optional and will only be send when changed
    reference string unique tenant identifier, eg '100004' - this is ALWAYS the reference to be persisted and the reference that will be used in future tenantReference values
    firstName string
    surname string
    languageCode string de, fr, it or en; must be lower case
    nationalityCode string ISO country code (ISO 3166-1 alpha-2), eg 'CH'
    phoneNumber string
    email string
    fullName string built from the individual name parts, respecting the type of tenant (corporate or physical)
    type string LEGAL (a company) or PHYSICAL (Physical person)
    dateOfBirth string ISO 8601 encoded date, eg '2019-05-30'
    allphoneNumbers array of hashes a list of all available email addresses and type
     phoneNumber string
     type string one of: PRIVATE, PROFESSIONAL, MOBILE or OTHER
    allEmails array of hashes a list of all available email addresses and type
     emailAddress string
     type string one of: PRIVATE, PROFESSIONAL or OTHER
    postalAddress hash current address fields conformant to the eCH-0010 specs
     addressLine1 string See eCH-0010 specs
     countryCode string ISO 3166-1 alpha-2 country code, eg CH
     city string
     zipCode string
     postOfficeBoxText string See eCH-0010 specs
     street string Street name including number where appropriate
     validFrom string Some Addresses will be created for the future

Example

Typical tenant updated message example:

NOTE: in most cases the tenantReference (prior reference) and tenant.reference (new reference) will be the same.

{"eventType":"Letting.Tenant.Updated",
  "data":{
    "tenancyAgreementReference":"10001.786.29.01",
    "unitReference":"10001.786.29",
    "tenantReference":"100004",
    "tenant":{
      "reference":"100004",
      "email":"[email protected]",
      "postalAddress":{
        "addressLine1":"Haupt Mieter",
        "countryCode":"CH",
        "city":"Bern",
        "zipCode":"3000",
        "postOfficeBoxText":"Postfach 1234",
        "street":"Hauptstrasse 1",
        "validFrom":"2024-01-01"
      }
    }
  }
}

Typical tenant merge message example:

NOTE: in the case of a merge the tenantReference (prior reference) is different from tenant.reference (new reference)

{"eventType":"Letting.Tenant.Updated",
  "data":{
    "tenancyAgreementReference":"10001.786.29.01",
    "unitReference":"10001.786.29",
    "tenantReference":"100004",
    "tenant":{
      "reference":"987654",
      "firstName":"Haupt",
      "surname":"Mieter",
      "languageCode":"de",
      "nationalityCode":"AT",
      "phoneNumber":"+41 31 331 21 11",
      "email":"[email protected]",
      "fullName":"Haupt Mieter",
      "type":"PHYSICAL",
      "dateOfBirth":"1980-01-01",
      "allphoneNumbers":[
        {"phoneNumber":"+41 31 331 21 11","type":"PRIVATE"},
        {"phoneNumber":"+41 31 331 21 12","type":"PROFESSIONAL"},
        {"phoneNumber":"+41 31 331 21 13","type":"MOBILE"},
        {"phoneNumber":"+41 31 331 21 14","type":"OTHER"}
      ],
      "allEmails":[
        {"emailAddress":"[email protected]","type":"PRIVATE"},
        {"emailAddress":"[email protected]","type":"PROFESSIONAL"}
      ],
      "postalAddress":{
        "addressLine1":"Haupt Mieter",
        "countryCode":"CH",
        "city":"Bern",
        "zipCode":"3000",
        "postOfficeBoxText":"Postfach 1234",
        "street":"Hauptstrasse 1"
      }
    }
  }
}