---
title: "Create a viewing request"
method: POST
path: "/viewing-requests"
tags: ["Viewings"]
---

# Create a viewing request

`POST /viewing-requests`

## Request

- Base URL: `https://platform-api.homejourney.sg/v1`
- URL: `https://platform-api.homejourney.sg/v1/viewing-requests`
- Auth: HTTP bearer

Creates a viewing request. Sandbox credentials use deterministic fixtures; live credentials create platform-attributed, side-effect-suppressed rows for public-safe platform listings. External URL: `/v1/viewing-requests`. Current Next.js implementation path: `/api/platform/v1/viewing-requests`. This mutating route requires `Idempotency-Key` and never sends SMS, WhatsApp, email, calendar writes, agent dispatch, or production webhooks in slice 1.

## Headers

- `X-Correlation-Id` string
- `Idempotency-Key` string, required

## Request body

- CreateViewingRequestRequest
  - `listing_id` string, required: Sandbox fixture listing ID for sandbox credentials or public-safe platform listing ID for live credentials.
  - `contact` object, required
    - `name` string, required
    - `phone` string, required
    - `email` string, email
  - `preferred_slots` object[], required
    - `date` string, required
    - `time_start` string, required
    - `time_end` string
    - `display` string
  - `message` string
  - `consent_to_contact` true, required

## Response `201`

Viewing request accepted.

- ViewingRequestResponse
  - `viewing_request` object, required
    - `id` string, uuid, required
    - `listing_id` string, required
    - `status` 'pending', required
    - `environment` 'sandbox' | 'live', required
    - `submitted_at` string, date-time, required
  - `livemode` boolean, required
  - `idempotency_key_hash` string, required
  - `request_id` string, required
  - `prepared_action` PlatformPortalListingViewingPreparedAction
    - `action_id` string, required
    - `status` 'prepared', required
    - `required_scope` 'viewings.write', required
    - `required_confirmation` 'first_party_app', required
    - `idempotency_required` true, required
    - `expires_at` string, date-time, required
    - `side_effects` object, required
      - `prepared_action_created` true, required
      - `action_prepared_event_created` true, required
      - `canonical_listing_mutated` false, required
      - `public_projection_mutated` false, required
      - `contact_delivered` false, required
      - `external_delivery_performed` false, required
    - `source_attribution` object, required
      - `listing_id` string, required
      - `source` 'platform_api', required
      - `source_projection` 'sandbox_public_safe_listing', required
    - `consent_boundary` object, required
      - `consent_text_version` 'platform-viewing-consent-v1', required
      - `consent_to_contact` true, required
      - `contact_data_included` false, required
      - `message_included` false, required
    - `safety` object, required
      - `delegated` false, required
      - `api_confirmation_allowed` false, required
      - `api_rejection_allowed` false, required
    - `continuation` object, required
      - `url` string, uri, required
      - `handoff_required` true, required
      - `reason` 'first_party_confirmation_required', required
    - `principal` Principal, required (unresolved $ref)

## Other responses

- `400`: Request validation failed.
- `401`: Missing or invalid platform API key.
- `403`: Credential, environment, or scope is not allowed.
- `404`: Platform API feature or resource is not available.
- `409`: Idempotency key is in progress or conflicts with an earlier request body.
- `429`: Rate limit exceeded.
- `500`: Unexpected platform API failure.

---

[API](https://skmtc.dev/homejourney/apis/homejourney-platform-api.md) · [All operations](https://skmtc.dev/homejourney/apis/homejourney-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/homejourney/apis/homejourney-platform-api/revisions/a2c6fe063db1?raw)