Integration-Sourced Data

Mental Model

Integration writes connect stable external identity to VRPlatform resources. Database mutations and external-system actions have different guarantees and must be presented separately.

Resources and Lifecycle

Connection-scoped writes can use connectionId, sourceId, uniqueRef, and an existing API id to resolve create versus update. Syncs and provider calls continue asynchronously after their initiating request.

PUT /syncs/{id} accepts queued, started, completed, or failed as status alongside sync metadata. Persist the authoritative result after provider work completes; repeating the same terminal status does not create another status-transition webhook or recipient setup-result event.

To cancel a sync, use POST /syncs/{id}/cancel. It cancels active subtasks, skips queued changes, and stops the attached Trigger run. Sending status: "canceled" to the update endpoint returns 400 without changing the sync.

Creating or reconnecting a property-management-system connection also queues initialization of missing reservation line mappings. The connection response confirms the provider connection, not completion of that background mapping work. Initialization reads the central defaults for that PMS, resolves stable account keys against the team's chart, and inserts only absent mapping rows. Existing mapping choices and exclusions are preserved.

Hostaway connections also reconcile their provider webhook after credentials are stored. The successful connection response does not wait for webhook creation, update, or duplicate cleanup.

Registered integration flow events are committed with their source mutation before any background wake-up. The response can therefore precede flow start, but a missed wake-up does not lose the event. VRPlatform retries each selected listener from the same durable event and delivery IDs, so one failed listener does not restart listeners already accepted by the flow runner.

Bank-record batches prefer an exact sourceId match. If an importer rotates that source row, the same uniqueRef on the same bank account still resolves the existing bank record and updates its source identity instead of creating a duplicate.

Read Model

Render batch data[] and item-level issues[], returned platform IDs, connection-scoped identity, source provenance, sync state, and operation progress. Do not infer that one accepted batch means every item or external action completed.

App discovery through GET /apps or GET /apps/{id} returns extension.url only when the app configures a browser-extension sign-in URL. Treat the optional field as absent for apps without that flow. The API does not expose the rest of an app's authentication configuration.

Whenever a flow operation accepts both flowId and connectionId, select the flow from that connection's app. A pair from different apps is rejected before any flow setting or mapping is read or changed; refresh the connection's flow list instead of retrying the mismatched IDs.

The same app responses expose validated extractor capabilities. A full extractor runs without a configured cursor window, while a cursor extractor uses the integration's configured range or cursor. A stored none value marks a disabled capability and is not returned. Offer an extractor as a manual fetch option only when visible is true. Show date-range inputs only when isDateRangeFetchable is true; the optional dateRangeMethod explains the provider date semantics when the integration supplies it.

Decision Table

Editability

Source ownership can make selected fields read-only. Team scope, connection scope, permissions, and existing journal locks still apply to imported resources. Never overwrite local fields merely because the external record has the same display name.

Flow contact mapping writes accept only contacts that still exist for the selected team. A stale contact returns 400 BAD_REQUEST with context.contactId. Refresh the available contacts before retrying.

Preview and Preflight

Database-backed contact, listing, reservation, transaction, AccountConnection, and bank-record batches take dryRun wherever the generated OpenAPI declares it. External operations cannot promise rollback. Dedicated migration preview endpoints report affected rows, locks, mappings, and cutover consequences.

For general-ledger teams, each new listing also receives its zero-value opening balance transaction during the listing batch. Journal materialization is queued after the response, so re-read accounting state instead of assuming those journal entries exist when the listing response arrives.

Import Data from CSV

Use the dedicated Import Data from CSV guide for the complete UI flow, example requests and responses, mapping and preset contracts, pagination, and recovery states.

CSV imports use only top-level /csv-imports routes. Existing fixed templates keep their synchronous Connection-scoped contract.

Mutation Recipe

1. Resolve team and connection.
2. Normalize and preserve stable source identifiers.
3. Load existing mappings or platform IDs.
4. Validate every item and relationship set.
5. Dry-run a supported database batch or request dedicated preview.
6. Present item outcomes and blockers.
7. Apply with the same identity and payload.
8. Persist returned platform IDs only from the real write.
9. Monitor asynchronous sync or provider state.

Failure and Recovery

Retry idempotently with the same external identity. Repair failed items from their structured issues instead of renaming references. For an uncertain provider result, read current connection or sync state before issuing another external action.

Legacy payment batches apply the same rule to nested lines. A line is stable within its payment by uniqueRef and line type; concurrent retries update that logical line even when each request generated a different internal row ID.

App connect and reconnect requests wait up to 25 seconds for provider work. Provider failures return 502 BAD_GATEWAY; the awaited limit returns 504 GATEWAY_TIMEOUT. The provider task may still be active after a timeout, so read the current connection state before retrying the external action.

Single-resource POST /connections/{id}/sync requests queue provider work and return a connection-sync operation acknowledgement. Poll GET /operations/{id} for the terminal outcome. Do not submit another request for the same resource while its operation is queued or running.

For Hostaway, read sync history when diagnosing webhook setup. Credential completion and webhook reconciliation are separate operations, so a successful connection can precede a failed or still-running webhook refresh.

If a PMS connection succeeds but expected reservation line mappings remain missing, rerun team initialization with lineMappings included. This recovery adds eligible missing mappings without replacing existing mapping choices.

If a bank record resolves to an Account that was removed concurrently, that item is skipped and returned in issues[]; other valid items can continue. Treat the issue as a request to refresh Account and AccountConnection identity, not as a reason to retry the stale relationship unchanged.

AccountConnection batch create and update groups are atomic. If rows conflict inside one group, the API rolls back that group and returns one structured issue per input instead of persisting a partial result. Correct the duplicate connection-scoped identity and retry the failed inputs.

Calendar block and unblock requests wait for provider confirmation. Past-date requests and provider denials recognized by the active integration return 400 BAD_REQUEST. The display message remains static and structured error context contains the provider-neutral calendarRequestRejected reason. PMS details remain inside the integration that owns their interpretation.

Banking integrations must return stable external account identity when credentials are completed. VRPlatform stores it as an AccountConnection. The built-in API app has no external account, so CSV bank-record imports use the canonical Account directly and do not require an AccountConnection.

Common Recipes

Upsert a reservation batch

Use stable connection-scoped references, dry-run the exact batch, resolve each item issue, apply, then store real reservation IDs and render calculated state.

POST /reservations/batch?dryRun=true
Content-Type: application/json

{
  "connectionId": "77777777-7777-4777-8777-777777777777",
  "data": [
    {
      "uniqueRef": "pms-reservation-1842",
      "listingId": "11111111-1111-4111-8111-111111111111",
      "status": "booked",
      "currency": "usd",
      "guestName": "Alex Morgan",
      "checkIn": "2026-08-14",
      "checkOut": "2026-08-18",
      "lines": [
        {
          "uniqueRef": "rent",
          "type": "rent",
          "description": "Accommodation",
          "amount": 125000
        }
      ]
    }
  ]
}

Start an OAuth connection

Use the connection flow, persist its state token server-side, handle the callback, and read the resulting connection. Do not offer a dry-run toggle.

If the callback request times out, retry the same callback payload. The API reuses the original provider task for one hour, so it does not exchange the provider's one-time authorization code twice.

POST /connections/connect
Content-Type: application/json

{
  "appId": "<app-id-from-get-apps>",
  "name": "Primary PMS",
  "redirectTo": "https://example.com/integrations/callback",
  "params": {}
}

API Reference

• Import listings — POST /listings/batch
• Import reservations — POST /reservations/batch
• Import account connections — POST /account-connections/batch
• Import bank records — POST /bank-records/batch
• Block calendar — POST /calendar-blocks
• Unblock calendar — DELETE /calendar-blocks
• Connect an app — POST /connections/connect

Related

• Integrate data