# RentZoobi XML feed v1 Use this guide to prepare an organization-scoped listing feed for RentZoobi. A feed delivery creates a reviewable receipt. An organization owner must apply an eligible receipt; listing authority, photos, moderation and publication remain separate steps. Availability depends on the service environment. Obtain the enabled API base URL and a feed credential through your RentZoobi organization. These instructions do not establish a live integration, a processing-time guarantee or compatibility with another listing site's XML format. ## Start here 1. Review your authority to supply each property, your rights to its content and which RentZoobi organization should receive it. 2. Open **Partner feeds** in your organization workspace. Create a source with a stable, recognizable name and store the issued credential in your server's secret manager. It is shown once. 3. Download [sample.xml](sample.xml), the [XSD](rentzoobi-feed-v1.xsd) and [field dictionary](field-dictionary.md). Replace synthetic values with authorized data in your own test environment. Never submit applicant, identity, screening, payment or lease records. 4. Send a dry run, inspect every row result, correct errors and then send an ordinary delivery with a new idempotency key. Dry runs cannot be applied. 5. Review the receipt in RentZoobi and explicitly apply it. Complete the normal listing review and publication workflow separately. For onboarding and feed issues, use the current support contact **info@rentari.ai**. Include the source name, delivery ID, timestamp and error code. Do not send credentials or private renter records by email. ## Transport and authentication `POST {API_BASE}/api/v1/partner-feeds/{FEED_ID}/deliveries?dry_run=true` Use `dry_run=false` for an ordinary staged delivery. If omitted, `dry_run` defaults to `true`; sending a preview never stages an applicable delivery. Required headers: | Header | Value | |---|---| | `Content-Type` | `application/xml` | | `X-Partner-Token` | The secret issued for this feed | | `Idempotency-Key` | A UUID unique to this intended request | Use HTTPS outside local development. The credential authorizes deliveries only for its feed and organization; it does not grant owner access, publication permission or cross-product data access. Keep separate credentials and source IDs for test and production environments. Do not place tokens in URLs, client-side code, source control, screenshots or logs. Example for a POSIX shell with the values already loaded securely into environment variables: ```sh # API_BASE, FEED_ID, PARTNER_TOKEN and DELIVERY_KEY come from your environment. # DELIVERY_KEY must be a UUID. Use a different key for dry run and ordinary delivery. curl --fail-with-body --request POST \ "$API_BASE/api/v1/partner-feeds/$FEED_ID/deliveries?dry_run=true" \ --header "Content-Type: application/xml" \ --header "X-Partner-Token: $PARTNER_TOKEN" \ --header "Idempotency-Key: $DELIVERY_KEY" \ --data-binary @sample.xml ``` In Windows PowerShell, use `curl.exe`, `$env:VARIABLE` syntax and PowerShell line continuation, or put the command on one line. `--data-binary` preserves the file bytes used for retry comparisons. Avoid verbose HTTP tracing because it can reveal headers. ## Document format and limits ```xml example-property 100 Example Lane Austin TX 78701 apartment unit Example apartment ``` - UTF-8, no XML namespace, root `RentZoobiFeed`, `version="1"`. - Required `sequence`: a positive integer from 1 through 2147483647. Increase it for each new ordinary delivery for this feed. - Maximum 524288 bytes (512 KiB) and 100 `Listing` records per request. - The submission limit is 60 attempts per feed per hour, including previews and retries. On HTTP 429, respect `Retry-After` before resuming. - Every listing has a stable `external_id` and explicit `action="upsert"` or `action="withdraw"`. - IDs are 1–120 characters: an ASCII letter or digit followed by ASCII letters, digits, `.`, `_`, `:` or `-`. IDs are scoped to the source and organization. Keep them unchanged and never reuse them for a different space. - Fields are case-sensitive, flat child elements listed in the dictionary. Their order does not matter. Unknown fields, duplicate fields, nested content and unexpected attributes are unsupported. - Escape XML text, including `&` and `<`. Plain text and CDATA text do not authorize HTML execution. DTDs, entity declarations and processing instructions are rejected; the XML 1.0 declaration shown above is allowed. - Omit unstated optional fields. Empty values are rejected. Omission does not mean false, zero, removal or withdrawal. The XSD helps catch structural mistakes. Server validation is authoritative for contextual requirements, supported inventory combinations, current taxonomy, credentials, sequence, current listing state and publication rules. ## Create, update and withdraw **Create:** use `upsert` with a new `external_id`. Supply `property_key`, `space_type` and `title`. For a property key the feed has not created before, also supply `address_line1`, `city`, `region`, `postal_code` and `property_type`. Use the same property key for multiple units in one property. A feed never attaches itself to a hand-created property by guessing from its address. The created listing is a draft. **Update:** send `upsert` using the same external ID. Only supplied listing fields and documented listing facts are eligible to change; omitted fields remain unchanged. Facts include bedrooms, bathrooms, area, amenities, utilities and fees. If you supply existing inventory facts, they must agree with the mapped property and space. V1 does not change inventory through a feed or clear fields with empty elements. Draft/state and version checks protect owner changes; inspect any conflict and revalidate the current content before applying a corrected delivery. **Withdraw:** send only the ID and action, as in [sample-withdraw.xml](sample-withdraw.xml). Applying a withdrawal pauses a live listing belonging to that source. A listing already off the market remains off. Omission from a later delivery does nothing. A withdrawal does not delete the property, applications, messages, agreements or payment history. Upsert does not automatically republish a withdrawn listing. Each source owns its mapping. Creating another source or sending the same address does not safely merge existing inventory. Contact the organization owner to review migration or duplication concerns before resending through a different source. ## Receipts, sequence and retries Receipts contain their ID, feed ID, sequence, state, timestamps, counts and row results. Row errors identify `field`, `code` and `message`. Inspect `allowed_actions` and all row outcomes instead of treating an HTTP success response as a published listing. Retrieve a known receipt with `GET {API_BASE}/api/v1/partner-feeds/{FEED_ID}/deliveries/{DELIVERY_ID}` and the same `X-Partner-Token` header. Machine receipt responses omit the source payload; authorized owners can inspect the normalized source fields in their workspace. Saving the delivery ID lets your sender retrieve the outcome after owner review. The organization workspace shows the source's state and last received/applied sequences. Source creation and credential changes remain owner actions. The owner source-creation limit is 20 attempts per organization per hour. | Receipt state | Meaning | |---|---| | `dry_run` | Validation preview only; cannot be applied | | `previewed` | Staged for owner review; eligible actions are supplied by the server | | `applied` | Owner application attempted; inspect row outcomes | | Row state | Meaning | |---|---| | `ready` | Eligible for owner application at the time of validation | | `invalid` | Correct the stated source fields before sending a new delivery | | `applied` | This row's eligible change was applied | | `conflict` | Target state or version changed; review and send a fresh delivery | | `unchanged` | No eligible change was necessary | Retry an uncertain request with **the same UUID, identical XML bytes and the same dry-run setting**. A valid retry returns the original receipt. Reusing a key for different bytes or a different dry-run setting returns a conflict. A corrected request needs a new key and, for an ordinary delivery, a sequence greater than the source's last received sequence. Dry runs validate the sequence without reserving it. Ordinary deliveries reserve their sequence on receipt. Applying a newer sequence prevents a stale older receipt from being applied later. Send and review deliveries in sequence order. Keep both your last acknowledged delivery ID and sequence in durable storage. Retry connection failures and temporary server failures with bounded exponential backoff and jitter. Do not continuously retry invalid XML, authorization denials, disabled capability or conflicts without fixing the cause. For a timeout after submission, retry the exact original request before generating a new one. ## Hosted collection Partners may serve this format from an approved HTTPS source. Support provisions the exact source URL and server credential for one RentZoobi feed and organization. An owner selects the approved source in **Collect a hosted feed**, confirms identity and saves a manual or scheduled collection policy. Source credentials are never entered in the browser or sent by email. Collection stages receipts under the same validation, identity and sequence rules as push deliveries. Owners still review and apply ready rows; publication remains separate. The collector rejects redirects, private-network destinations, compressed responses and oversized content. It records fixed safe result/error codes and a link to the latest received delivery. An unchanged file reuses its existing receipt, including any conflicts. After a destination edit, resolve the conflict and revise the source to produce a new higher sequence; re-collecting unchanged content does not overwrite the destination or create a fresh review. HTTP 204 does not imply withdrawal. **Collect feed now** performs a manual refresh. Scheduled collection uses a configured worker and a 60–1,440 minute interval; saving settings alone does not activate that worker. **Pause scheduled collection** stops future scheduled work while retaining listings and receipts. Environment availability and source access remain independent prerequisites. See the [Rentari connection guide](rentari-integration.md) for the dedicated Rentari export, source permissions and operator handoff. ## Freshness and operations Send changes according to the cadence agreed during onboarding, especially availability, prices and withdrawals. Push delivery and approved hosted collection both use explicit withdrawals; neither infers deletion from absence. There is no automatic stale-source expiry, processing-time promise or outbound receipt webhook in this contract. Delivery timestamps and sequences support operational review; keep checking receipts and listing state. Owners can rotate or revoke a feed credential. Rotation invalidates the previous credential immediately; there is no overlap window. Arrange a brief sender pause, rotate through the owner controls, update the secret manager and resume with the new credential. Revocation stops future authenticated submissions and application of staged receipts. Review live listings separately; credential revocation is not a withdrawal instruction. The receipt retains normalized source fields and validation outcomes for review. Keep private data out of feeds and support tickets. Do not assume an automatic retention/deletion period; organization retention requests require support review. ## Media, rich fields and other formats V1 accepts the documented flat listing fields and registry facts, including amenities and fees listed in the dictionary. It does not import photo URLs, floor-plan files, external links, applicant/contact data, undocumented custom fields, property hierarchy or billing instructions. A `floor_plan` value is a plan name, not a file. Complete photos and remaining required information through the existing RentZoobi listing workflow. Use only media you have rights to publish; a feed's acceptance does not verify those rights. Stating a fee does not collect it or establish that it is permitted for the listing's jurisdiction. Zillow/ZIF, MITS, Yardi/RentCafe, AppFolio and other provider formats require a separately verified adapter. No vendor certification or integration is implied. Hosted collection is limited to approved sources producing RentZoobi XML v1. FTP/SFTP, ZIP/gzip uploads, automatic publication and outbound lead routing are not part of this version. ## Before activation - Confirm organization/source mapping, authorized inventory, content rights and support contacts. - Validate a synthetic sample, correction, duplicate retry, conflicting retry, stale sequence and explicit withdrawal in the intended test environment. - Verify scoped credentials and immediate rotation/revocation behavior. - Confirm who reviews/applies receipts and completes publication checks. - Agree the refresh/withdrawal procedure and inspect failed or stale deliveries operationally. - Obtain the environment's release and partner onboarding approval. A sample or passing dry run alone does not activate production. See the [field dictionary](field-dictionary.md) and [troubleshooting guide](troubleshooting.md).