Skip to main content

Units

A unit belongs to a building. This endpoint creates and updates units. The same item shape is also accepted nested inside a prospect to create a unit on the fly.

See the Onboarding overview for the array, result, and upsert conventions this endpoint shares.

Create or update units​

POST /partners/{owner_slug}/units
Content-Type: application/json
[
  { "external_system_id": "acme-unit-456",
    "property_external_id": "acme-prop-123",
    "address": {
      "line_one": "1101 Midland Avenue APT 01",
      "line_two": null,
      "city": "New Brunswick",
      "state": "NJ",
      "zip": "08901"
    },
    "pms_unit_id": "0401",
    "default_coverage": { "type": "multiplier", "value": 1.5 } }
]

The example omits name, so Rhino derives it as "01" from the address.

Request fields​

FieldRequiredNotes
external_system_idyesYour own identifier. The upsert key
property_external_idyesYour property identifier, never a Rhino one
namenoUnit number or name. When omitted, it is derived from address. Sending it always takes precedence over derivation
addressnoThe unit's full address, exactly as stored, including any line 1 and line 2 inconsistency, designators, and extraneous text. Object: line_one, line_two, city, state, zip. Used to derive the building street and, when name is absent, the unit's label. line_two is not read for identity
pms_unit_idnoThe PMS unit code, when applicable. For an owner with an existing Rhino relationship, send it: it is the primary unit match key
default_coveragenoInherits from the property when absent

Response​

{
  "status_code": 200,
  "results": [
    { "external_system_id": "acme-unit-456", "action": "created" }
  ],
  "meta": { "created": 1, "updated": 0, "failed": 0 }
}

Units key on property_external_id, so properties and units may be sent in the same pass. A property_external_id that Rhino does not recognize fails that item, so send the property first, in the same request or an earlier one. Sending a building's units in a single request is recommended, because it resolves the building's derived address and unit names immediately.

Unit name derivation​

When name is absent, the label is derived, in order:

  1. The designator found in the unit's own street line ("APT 01" yields "01").
  2. The street line with the building's established street removed, so a bare "…Blvd. 208" resolves to "208".
  3. A designator in line_two.
  4. The pms_unit_id.

A single unit building defaults to "1". Standard designator words are dropped ("APT 01" yields "01"); nonstandard ones are kept verbatim, such as "5th Floor" or "Loft B". Where nothing is derivable in a multi unit building, the item fails with "unit name required and not derivable", because Rhino never guesses a label that will appear on a policy.

Unit matching​

Within the parent building, in the same order as properties:

  1. If external_system_id is already linked to a unit, that unit is updated.
  2. PMS code, when sent. An existing unit with the same pms_unit_id is adopted and linked. This match is exact and unaffected by naming style, which is why an owner with an existing Rhino relationship should always send it: a derived name such as "113" may not match the PMS's stored "0113".
  3. Otherwise, by name, ignoring case. A unit already linked to a different identifier fails the item, as with properties.
  4. Otherwise, create.

One unit buildings. A property of type single_family or garden_community holds exactly one unit; a second unit sent for it fails as an individual item error.

There is no unit level removal; a unit cannot be individually deactivated. Remove the whole building with the property's active: false, or resolve it with your Partner Success Manager.

Next steps​