# External-agent discovery-to-booking example

This is the customer-safe machine flow. Do not drive the human website or the private Hub.

## 1. Discover

`GET https://elron.club/api/public/v1/rentals?locale=en&city=Basel&durationMonths=6`

Read the selected `rentalId`, current availability, duration price, deposit, terms, eligibility, and media from the response. Recheck the rental immediately before starting an application.

## 2. Start and verify

`POST https://elron.club/api/public/v1/applications` with a unique `Idempotency-Key` header, current privacy-consent version, contact data, and the selected `rentalId`. The response contains an opaque `session.token`; it never contains the email-verification link. The applicant must use the separately delivered email before mutation tools will progress.

## 3. Coordinate a viewing when needed

Read `GET https://elron.club/api/public/v1/applications/{sessionToken}/viewings`. Propose one to five slots with `POST .../viewings/availability`, the exact `applicationVersion`, and an `Idempotency-Key`. Accept or decline only a pending Elron proposal at `POST .../viewings/proposals/{proposalId}/respond` with `responseConfirmed: true`.

## 4. Complete applicant data and documents

Patch the verified application using its exact current version. For each document, call `applications.create_document_upload` (`POST .../documents/uploads`), submit the binary as the signed form's `file` field without changing any returned field, then call `applications.complete_document_upload` (`POST .../documents/uploads/{uploadSessionId}/complete`). Do not embed document bytes in the preferred agent flow. Submit only with explicit current credit-check and truth-confirmation consent.

## 5. Quote and availability hold

After Elron Club review reaches the approved state, create and read a quote. `quotes.accept` requires the exact quote version and explicit acceptance; it creates only the returned expiry-bound availability hold, not a contract, payment, or booking.

## 6. Legal, payment, and confirmation gates

Use the scoped contract-signing read only when it returns an active signer link for the verified applicant. The human completes provider verification and signature. `payments.get_status` reports payment truth. Follow `authorizationUrl` only when it is non-null and `authorizationExpiresAt` is still in the future; otherwise use the approved billing channel. The production provider remains unconfigured until separately reviewed and authorized. A booking exists only when `bookings.get_confirmation` returns an authoritative Stay-backed confirmation.

## Retry rules

- Reuse the same idempotency key only for an exact replay.
- On `STALE_VERSION`, reread the scoped resource and review it before using a new key.
- On `CAPABILITY_STATE_INCOMPLETE`, do not retry that key; request reconciliation.
- On `RATE_LIMITED`, wait for `Retry-After`.