Portfolio Health

Use GET /teams/issues to read current open issues across accessible teams in one regional data partition. Use a partner API key for a managed portfolio or a team API key for that team's scope.

For an interactive partner UI, discover available partitions from GET /me at partnerContext.managedTeamRegions. Send x-data-region when reading a partition. The API does not merge multiple regions in one response; call each advertised regional API base URL independently when the screen needs the full portfolio.

Pagination and Filters

• teamIds: optional comma-separated team UUIDs; omit for all accessible teams.
• codes: optional comma-separated values from the Issue Catalog.
• includeEmptyTeams: include teams with no open issues.
• view=summary|detail: view=detail (default) includes each issue's code-specific context; view=summary omits it.
• limit: 1 to 100.
• cursor: opaque value returned by the previous page.

Pass cursors back unchanged. Cursors belong to one region and filter set, so reset them when switching region. Requested teams outside the credential's access scope are not disclosed.

Snapshot Contract

Each team result includes teamId, teamName, snapshotVersion, computedAt, issues[], and summary counts.

• snapshotVersion increases only when normalized open issue content changes.
• computedAt also changes after a no-op reconciliation and indicates freshness.
• Issue id is stable for one team and code.
• Issue feature is a stable grouping key for partner-native queues. Current values are accounting, banking, billing, connections, listings, reconciliation, reservations, statements, and team.
• If a resolved issue later reopens, its ID is reused and version increases.
• summary.total counts open codes; affectedTotal sums their affected values.

Never parse issue title or message. Branch on code, feature, severity, category, and context. Use each issue's generated documentationUrl to open its catalog entry in the public documentation.

Mutation responses do not wait for portfolio-health recomputation. A successful write persists its audit record, then marks only health checks that depend on the changed resource types. Deferred effect mutations use the same durable dirty-state path. The regional evaluator runs every minute and continues while work remains. Re-read GET /teams/issues until computedAt advances when a workflow needs the refreshed health state.

Checks that can change because time passed or an external system changed are also reconciled within a 15-minute window. Teams are spread deterministically across that window, so a regional portfolio is not recomputed in one burst. Pending work is durable and remains eligible for later scheduled evaluators. These scheduling details do not change the snapshot or issue lifecycle contract returned by the API.

Reservation Journal Refresh Issues

journalLocked, journalConfigurationInvalid, and journalUnbalanced identify outstanding failed refreshes on active reservations. They reuse the reservation's journalStatus classification. A normal accounting lock on a current journal is not an issue. Inactive reservations, applied revisions, and failures still being retried do not contribute to these codes. A separate exhausted failure can still require attention while another refresh is running.

Each code has the normal stable team/code issue ID, version, documentation link, and source-controlled lifecycle. In detail view, context.action gives the supported recovery action and context.reservations lists affected reservation IDs, confirmation codes, staleSince, and calculatedAt. affected counts reservations once per code. Summary view omits context.

GET /teams/issues?codes=journalLocked,journalConfigurationInvalid,journalUnbalanced&view=detail

Use an affected reservationId to request GET /reservations/{id}/journal-preview in that team's context. The preview returns current lock details, account/fee references, or proposed imbalance amounts. It requires reservation-read access and is unavailable to owners. Listing a team issue does not grant access to its reservation preview.

The portfolio snapshot records an outstanding failure; it does not run previews or store their sampled details. Configuration or locks may have changed since the last attempt, so the preview can return a different reason, ready, or unchanged. Use the current preview for the review screen. Reading it does not resolve the portfolio issue or acknowledge an unapplied refresh.

journalUnbalanced refers to a failed proposed refresh. The existing unbalancedJournalEntries code checks stored postings. Neither code is a payout difference. Both may exist for the same reservation and must not be added together as distinct affected reservations.

Effect failures and retries can happen without a journal mutation. These codes also use scheduled reconciliation, so they can lag effect transitions by the existing 15-minute window. A retry removes its terminal-failure issue after evaluation; another failure reopens the same team/code ID. No refresh, repair, unlock, or freshness enforcement is triggered by reading or evaluating these issues.

See Reservation editability for the preview contract and recovery details.

Bank Connection Health

brokenConnections includes active bank connections from supported services whose shared bank-feed assessment is warning, actionRequired, or unknown. The account badge and this issue use the same assessment rules. Portfolio Health reads a materialized snapshot, so its result can lag a current account read until recomputation. Compare computedAt with the health observation timestamps.

In detail view, context.connections[].health contains the same public health shape returned on the connection. Preserve each nested issue's account scope and use only its returned recovery actions. unknown means current evidence is insufficient; it does not imply that the customer must reconnect. See Stored Bank Feed Health for statuses, reasons, observation times, and actions.

Each connection appears once even when it has several affected accounts or a legacy failure flag. affected counts connections. The portfolio issue has severity error if any supported connection requires action or another integration has a legacy failure. It is warning when all included connections have warning or unknown health. A supported connection assessed as healthy contributes no legacy failure alert. Other integrations retain their existing failed-connection checks.

Changed integration observations durably schedule recomputation. Periodic reconciliation also catches consent expiry, aging observations, and changed service capabilities. Verified recovery removes the connection from the issue; the issue resolves when no affected connections remain.

Initial Materialization

If any team in the request scope lacks its first materialized snapshot, the whole request fails with 503 SERVICE_UNAVAILABLE; no partial result is returned for the teams that do have snapshots. The structured context lists only the affected teams in pendingTeamIds, with a retryAfterSeconds hint. A pending team is not silently treated as healthy. To recover, retry the same request after retryAfterSeconds, or scope teamIds to exclude the pending teams and read the rest immediately. Alert if materialization remains unavailable.

Task Ownership and Lifecycle

The API owns issue state. There are no close, reopen, or snooze mutations:

• an issue is open while its catalog trigger is true;
• it resolves and disappears from the response when the source condition is corrected;
• it reopens with the same id and a higher version if that condition later returns; and
• Hostaway may snooze a task in its own UI, but snooze never changes the API state. Reconsider a local snooze whenever the issue version changes.

Use feature to build queue sections and the code-specific context or catalog fetch guidance to open a repair workflow. VRPlatform does not return a Hostaway application URL because the parent application owns its navigation. documentationUrl points to technical guidance, not an in-product action.

Calendar reminders, month-end checklists, and other scheduled work are not issue codes. The partner application owns their cadence and presentation. Add an issue code only when VRPlatform can detect a current source condition and automatically resolve it after correction.

For analytics, treat (teamId, issue.id, version) and snapshot changes as the event identity. For support assistants, use documentationUrl, the generated catalog guidance, and current issue context; no separate AI-specific issue payload is required.

UI Pattern

Use summary view for portfolio queues. Fetch detail when a user opens a repair workflow. Keep region identity on every queue row if the UI combines regional responses. Replace current team state after every newer snapshot; do not retain resolved codes.

Exact contract: List team issues.