Delegate apartment resident management via API

Shared apartment buildings need delegation: the building operator owns the intercom and common doors, while each apartment manages its own residents for directory display and permissions. OpenApp exposes this through building users on a Virtual Access integration (/integrations/{id}/building-users).

This guide is for integrators and building admins automating resident lists — not for guests. See Model by sector (shared apartment building).

Prerequisites

• Virtual Access integration id (INTEGRATION_ID)
• Organization id and API key with permission to update the integration
• Target user’s OpenApp user_id and the role string your deployment expects (often scoped to the integration)

Full SDK reference: Apartment residents.

List current building users

export OPENAPP_API_BASE='https://api.openapp.house/api/v1'
export OPENAPP_API_KEY='v1_openapp_YOUR_SECRET'
export OPENAPP_ORG_ID='01HORG00000000000000000000'
export INTEGRATION_ID='01HINTEGRATION00000000000000'

curl -sS \
  -H "Authorization: Bearer ${OPENAPP_API_KEY}" \
  -H "X-Org: ${OPENAPP_ORG_ID}" \
  "${OPENAPP_API_BASE}/integrations/${INTEGRATION_ID}/building-users"

Python (SDK)

rows = await client.apartment_residents.list(integration_id)

Ensure X-Org is sent if your client does not inject it automatically — see the Apartment residents note on headers.

Add a resident to an apartment’s delegation

curl -sS -X POST \
  -H "Authorization: Bearer ${OPENAPP_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Org: ${OPENAPP_ORG_ID}" \
  -d '{
    "user_id": "01HUSER00000000000000000000",
    "role": "virtual_access:integration:'"${INTEGRATION_ID}"':resident"
  }' \
  "${OPENAPP_API_BASE}/integrations/${INTEGRATION_ID}/building-users"

Replace role with the value shown in your org’s role catalog (API reference → Roles).

Python (SDK)

await client.apartment_residents.add(
    integration_id,
    user_id=user_id,
    role=role_string,
)

Remove a resident

curl -sS -X DELETE \
  -H "Authorization: Bearer ${OPENAPP_API_KEY}" \
  -H "X-Org: ${OPENAPP_ORG_ID}" \
  "${OPENAPP_API_BASE}/integrations/${INTEGRATION_ID}/building-users/${USER_ID}"

Python (SDK)

await client.apartment_residents.remove(integration_id, user_id)

Automation patterns

Pattern	Approach
Apartment portal in your app	On “add roommate”, call POST .../building-users
Sync from property DB	Nightly job: diff list vs source of truth
Offboarding	DELETE .../building-users/{user_id} on lease end

Pair with Virtual intercom flow so delegated residents appear in the lobby directory.

---

← Virtual intercom · Open a PalGate gate →