Legacy (VRI) Migration

VRI is the legacy VRPlatform product generation that ran without a general ledger; VRT is the current generation with full general-ledger accounting. Migrating a VRI team to a VRT team is a staged flow: bootstrap the new team, map legacy statement accounts and listings onto the target team, then import the historical owner statements.

POST /internal/migrate-vri-to-vrt — create the GL team from the legacy source and provision its chart of accounts, statement layouts, and recurring fees.
GET /internal/migrate-vri-to-vrt/statements/account-mappings — see which legacy accounts need mapping.
GET /internal/migrate-vri-to-vrt/statements/listing-mappings — see which legacy listings need mapping.
POST /internal/migrate-vri-to-vrt/statements — import historical statements with explicit mappings.

Bootstrap requires an API key with access to the source team; the mapping and statement-import routes require access to both the source and the target team. A team is accessible when it is the key's own team or a team managed by the key's partner. Contact VRPlatform if your key lacks access.

Concepts

Effective cutover

glStartAt on the bootstrap request is the minimum requested cutover. The migration pushes the effective cutover forward to the first day of the month after the source team's last posted/published owner statement, so live GL accounting never overlaps months the legacy team already settled.

Historical ledger

Imported statements and their journal entries land on ledger = historical. They preserve the owner-facing history (balances, statement PDFs/views) without mixing into the live general ledger that starts at the cutover.

Account mappings

Legacy statements reference VRI accounts that do not exist on the new chart. Each legacy account found on importable statement lines must resolve to one target account. A hardcoded mapper covers the common cases; everything else needs an explicit mapping — the same fetch-then-post pattern as PMS migration listing mappings.

Listing mappings

Historical statements must attach to target VRT listings and ownership periods. Teams created by the bootstrap flow already have deterministic target listing ids. Manually created VRT teams often have different real listing ids, so the statement import supports explicit legacy-to-target listing mappings.

When an explicit mapping targets an existing VRT listing, the import reuses the native ownership period active at the effective cutover and extends its start to inception. Historical statements attach to that period instead of creating a duplicate period ending at the cutover. A rerun removes the replaced imported period after its statements and journal entries have moved. Later real owner changes remain separate periods.

Use targetListingId to attach legacy statement history to an existing VRT listing. Use targetListingId: null only when the legacy listing has no VRT match and should be imported as an inactive historical-only listing.

1. Bootstrap the GL team

POST /internal/migrate-vri-to-vrt

{
  "sourceTenantId": "legacy-team-uuid",
  "targetPartnerId": "optional-partner-uuid",
  "targetName": "Mountain Papa",
  "glStartAt": "2025-01-01",
  "moveConnectionCredentials": false
}

Copies only the narrow bootstrap state:

tenant shell, listings, and owner identities (as contacts);
connection shells — credentials stripped and disabled = true unless moveConnectionCredentials is true, which moves credentials over and clears them on the source so OAuth/token integrations are never live twice;
derived ownership periods, preferring historical statement-owner snapshots from glStartAt forward and falling back to current listing owners. The first ownership starts at inception, and the GL cutover does not split unchanged ownership.

Bootstrap finishes by initializing the target team's chart of accounts, statement layouts, and recurring fees from the default template, so the mapping previews below work immediately. Tax rates and line mappings are not part of this initialization; run POST /team/init with the target team in x-team-id if the team needs them. No statements are imported yet — that is the follow-up flow below.

2. Review account mappings

GET /internal/migrate-vri-to-vrt/statements/account-mappings
  ?sourceTenantId=...&targetTenantId=...

Returns the legacy accounts that the current migration plan would import, with a suggestion per account and the target account pool:

{
  "effectiveGlStartAt": "2025-02-01",
  "oldAccounts": [
    {
      "legacyAccount": {
        "key": "legacy-ref:341",
        "ref": "341",
        "name": "Rental Income",
        "classification": "Revenue"
      },
      "sources": ["line", "template"],
      "suggestedTargetAccount": { "id": "rents-uuid", "title": "Rents" },
      "currentTargetAccount": null
    }
  ],
  "newAccounts": [
    {
      "id": "rents-uuid",
      "title": "Rents",
      "category": {
        "id": "category-uuid",
        "name": "Revenue",
        "classification": "revenue"
      },
      "type": "ledger",
      "status": "active"
    }
  ]
}

suggestedTargetAccount is the hardcoded mapper's pick; null means the account needs an explicit user choice.
currentTargetAccount reflects mappings stored by a previous import run, so reopening the mapping screen shows what is already resolved.
Only legacy accounts on imported, non-zero, non-payout statement lines are listed; template-only accounts are skipped.

3. Review listing mappings

GET /internal/migrate-vri-to-vrt/statements/listing-mappings
  ?sourceTenantId=...&targetTenantId=...

Returns legacy listings used by importable historical statements, exact uniqueRef target suggestions, and the target listing pool:

{
  "effectiveGlStartAt": "2025-02-01",
  "oldListings": [
    {
      "legacyListing": {
        "id": "legacy-listing-uuid",
        "name": "Ravensong",
        "uniqueRef": "461898",
        "status": "active",
        "pmsStatus": "active"
      },
      "importedStatementCount": 12,
      "suggestedTargetListing": {
        "id": "target-listing-uuid",
        "name": "Ravensong",
        "uniqueRef": "461898",
        "status": "active",
        "pmsStatus": "active"
      },
      "currentTargetListing": null,
      "currentMapping": null
    }
  ],
  "newListings": [
    {
      "id": "target-listing-uuid",
      "name": "Ravensong",
      "uniqueRef": "461898",
      "status": "active",
      "pmsStatus": "active"
    }
  ]
}

suggestedTargetListing is set only when exactly one target listing has the same uniqueRef as the legacy listing.
currentTargetListing and currentMapping show what a previous import run stored.
currentMapping = "historicalListing" means the source listing was imported as an inactive historical-only listing.

4. Import historical statements

POST /internal/migrate-vri-to-vrt/statements

{
  "sourceTenantId": "legacy-team-uuid",
  "targetTenantId": "migrated-team-uuid",
  "accountMappings": [
    {
      "legacyAccountKey": "legacy-ref:341",
      "targetAccountId": "rents-uuid"
    }
  ],
  "listingMappings": [
    {
      "sourceListingId": "legacy-listing-uuid",
      "targetListingId": "target-listing-uuid"
    },
    {
      "sourceListingId": "legacy-listing-without-vrt-match-uuid",
      "targetListingId": null
    }
  ]
}

Each accountMappings[] entry binds one oldAccounts[].legacyAccount.key from the preview to one target account id. Explicit mappings win over the hardcoded mapper.
Resolved mappings are stored on the target team, so the import can be rerun and the preview returns them as currentTargetAccount.
listingMappings[] works the same way for listings: one oldListings[].legacyListing.id from the listing preview per entry, bound to one target listing id or to null for an inactive historical-only listing.
Exact uniqueRef listing suggestions are applied when no explicit listing mapping is sent for that source listing.
The import brings over pre-cutover owner statements, their provenance rows, attached historical journal entries, and statement templates rewritten onto the target chart. Only statements that attach to derived ownership periods are imported.
Explicit mappings onto existing VRT listings reuse the native ownership period active at cutover. This keeps migrated history and native statements on one ownership timeline when the owners did not change.
On success, the target team's statementStartAt moves to the effective cutover and historicalStatementsImportedAt records the run.

Exact contracts

The migration routes are tagged internal and are not part of the generated public API reference. They are provided during migration onboarding together with access for your key.

PMS Migration
Historical Statements — the generic import that creates the same historical-ledger statements from any source.
Statements and Reporting Periods
Ownership and Attribution
Banking and Accounts

Legacy (VRI) Migration

On this page