Writes and readback
On this page
Preview changes, write deliberately and recover an uncertain outcome.
REST operations and key permissions
| Task | Key permissions | Start here |
|---|---|---|
| Preview and commit properties and units | write:properties; read:properties for readback | POST /api/v1/landlord/portfolio-imports/preview |
| Read or import commercial rent rolls | read:rent-roll; write:rent-roll for import | GET /api/v1/landlord/rent-roll |
Preview, inspect, commit and read back
Start with the existing two-step portfolio import: create an immutable preview, inspect its validity and blocking issues, then commit that preview with {"confirm":true}. Read GET /api/v1/landlord/portfolio-imports/{importId} to verify the durable result. Creating a preview also persists data and requires write permission.
Keep one identity for each write
Every landlord mutation requires an Idempotency-Key of 16–200 characters, using only ASCII letters, digits, periods, underscores, colons or hyphens, without surrounding whitespace. Create one key per logical operation and preserve the exact request body and key. Use a separate key for preview and commit. Successful responses have a 24-hour replay window, scoped to the same API key and operation.
Recover an unknown write outcome
After a lost response, read the resource or operation back if its returned ID is known. If no returned ID is known, retry the identical request with the original Idempotency-Key and original API key within 24 hours of the first attempt. If that window has elapsed or safe readback/replay is unavailable, stop and reconcile the outcome; neither reusing an expired key nor choosing a fresh key guarantees that a write will not run again. Import previews, jobs and their history remain bound to the key that created them.
Preserve application capabilities
Versioned application submission has a different contract: preserve its UUID X-Application-Submission-Key, receipt and upload keys. Follow the published receipt/progress operations before retrying. The landlord Idempotency-Key does not replace those capabilities.
Use the published contract version
Use the API version and lifecycle shown in the API reference, the schemas for each operation, and any required form or resource version when updating an integration. Preserve opaque versions unchanged and pin an approved MCP release. Event names come from the same catalog as the API; arrival order and a product version are not substitutes for current resource readback.