Skip to content
Documentation

Get started

Build across the property journey.

Use the Homejourney Platform API or AI Connect MCP endpoint to connect organizations, property journeys, professional workspaces, and compatible AI clients.

Create API keyAI Connect guideAPI reference (opens in a new tab)

AI Connect

Connect any compatible AI client.

Homejourney exposes one standards-based MCP endpoint for AI clients. Tool access is governed by OAuth scopes and the user's authorized Homejourney workspace, not by host-specific integrations.

Hosted Streamable HTTP MCP endpoint

https://ai-apps.homejourney.sg/mcp

Set up your AI agent

Set up Homejourney for me. Fetch https://www.homejourney.sg/ai.md and follow it.

Paste it into Claude Code, Codex, Cursor or another agent. It adds the MCP server itself.

Authorize with OAuth

Authorization code, dynamic client registration, and S256 PKCE for public clients. Bearer tokens carry the approved scopes.

Keep access proportional

Public-safe reads can remain unauthenticated. Private reads and writes require the matching account, role, workspace, and consent.

Confirm consequential work

Write tools declare their behavior and retain Homejourney confirmation, idempotency, audit, and owned handoff controls.

Connection sequence

  1. 1.Add the hosted MCP endpoint to any compatible AI client.
  2. 2.The client discovers Homejourney OAuth and registers as a public PKCE client.
  3. 3.Homejourney requests only the scopes needed for protected tools.
  4. 4.The client calls tools within their read, write, and confirmation annotations.
  5. 5.Users can review and revoke connected AI access from Homejourney settings.

Discovery documents

Protected resource metadata (opens in a new tab)Authorization server metadataPlatform status (opens in a new tab)

Access and safety boundaries

  • Public discovery returns public-safe Singapore property, service, finance, and news data.
  • Private data and workspace tools require a signed-in Homejourney account and matching OAuth scopes.
  • Consequential actions require explicit confirmation, idempotency, and Homejourney audit controls.
  • Identity checks, sensitive consent, and payments continue on Homejourney-owned pages.
  • AI Connect acts for a signed-in Homejourney user through OAuth, not with a platform API key, so the API product catalog does not list its tools.
  • A developer's own assistant can read their API Console onboarding steps and create a sandbox (hjp_test_) key once they confirm; signing up, the platform terms, live keys and the live access review request stay in the API Console.
  • The same assistant can list their valuation widget keys with each one's snippet, and create a sandbox (hje_test_) widget key for the websites they name once they confirm; live widget keys and revoking stay in the API Console.

Integration and review support: [email protected]

Quickstart

Make your first request

Create a sandbox key in the API Console, then request the organization attached to that credential. Sandbox and live credentials are always isolated.

curl https://sandbox-platform-api.homejourney.sg/v1/organizations/current \
  -H "Authorization: Bearer hjp_test_your_key" \
  -H "Accept: application/json"

Authentication

Use scoped bearer credentials

Send your platform API key in the Authorization header. Never expose a live key in client-side code or commit it to your repository.

Authorization header

Authorization: Bearer hjp_test_your_key

Environments

Develop safely in the sandbox

Sandbox credentials use deterministic test fixtures and cannot authenticate against live hosts. Live keys come only after live access review.

Sandbox

hjp_test_
https://sandbox-platform-api.homejourney.sg/v1

Live

hjp_live_
https://platform-api.homejourney.sg/v1

Go live

Pass live access review.

Live keys come only through live access review. A Homejourney reviewer checks your sandbox integration and the items below, and no live key exists until they approve. There is no report or file to export: you record each item, then request the review.

What the review checks

  • Platform terms accepted
  • A support contact: the person Homejourney contacts when your integration has a problem
  • A sandbox key, used to build and test your integration
  • Who signs for your business, with the ACRA BizFile reference that names them
  • Your business details: UEN, registered name and address
  • Your signed partner contract: its reference, who signed it and when
  • Fees and payouts, which Homejourney agrees with you
  • To send your agency’s listings: your estate agent licence, matched against the CEA register

How to request it

  • API Console: open Developer tools, record each item under Going live, then request the review under Live access.
  • API, with a sandbox key that has onboarding.write: POST /onboarding/evidence for each item, then POST /onboarding/live-access/request. GET /onboarding/readiness lists what is still missing.

Platform APIs

One API for connected property operations

Start with the surface closest to your product, then follow its scopes and related workflows in the REST reference.

Organizations

Start with account context

Resolve the organization, credential environment, scopes, products, and onboarding readiness for an integration.

GET /organizations/current

Property products

Connect real estate workflows

Build on listings, partner sites, official-source datasets, viewings, mortgage journeys, and service operations.

GET /products

Agents and agencies

Power professional workspaces

Read sandbox-safe listings, teams, analytics, viewings, distribution, and integration readiness.

GET /agents/current

Developer inventory

Publish and coordinate projects

Work with projects, unit types, inventory batches, price lists, media, showflat slots, and lead routing.

GET /developers/current/projects

Webhooks

React to platform events

Register endpoints, inspect delivery evidence, create sandbox test events, and safely replay deliveries.

GET /webhooks/endpoints

Listings

Read listings, or send your agency’s own.

Each route needs the scope shown beside it on your API key. The REST reference has every field, filter and sandbox test case.

Read listings

Pull Homejourney listings into your CRM, website or app. Responses never include agents’ private contact details.

  • GET /listingslistings.read
  • GET /listings/{id}listings.read

Available today. Sandbox keys return fixed test listings. Live keys return active public listings from Homejourney owners, agents and partner sources, once your organization passes live access review in the API Console.

Send your agency’s listings

For CEA-licensed estate agencies. Each listing names the salesperson who markets it and the agency’s marketing authority, and a Homejourney reviewer checks it before it goes live.

  • PUT /listing-feed/listings/{externalRef}listings.write
  • GET /listing-feed/listingslistings.read
  • GET /listing-feed/listings/{externalRef}listings.read
  • DELETE /listing-feed/listings/{externalRef}listings.write

Sandbox today, where you can try every step. Live access is planned: it opens to licensed estate agencies one at a time through live access review, which grants listings.write.

Search filters

GET /listings and the AI Connect search_listings tool take different filters. REST also takes the tool’s price_min and price_max. A dash means that side has no such filter.

Text searchRESTqMCPquery
Sale or rentRESTlisting_typeMCPlisting_type
Property typeRESTproperty_typeMCPproperty_type
DistrictRESTdistrictMCPdistrictdistricts
PriceRESTmin_pricemax_priceprice_minprice_maxMCPprice_minprice_max
BedroomsRESTbedrooms_minbedrooms_maxMCPbedroomsbedrooms_minbedroom_counts
Room or whole unitRESTsubletting_typeMCPsubletting_type
Available fromRESTavailable_fromMCPavailable_from
Lease lengthRESTlease_duration_monthsMCPlease_duration_months
SortRESTsortMCPsort
BathroomsREST–MCPbathrooms_minbathroom_counts
HDB flat typeREST–MCPhdb_flat_types
Landed house typeREST–MCPlanded_house_types
TownREST–MCPtowns
ProjectREST–MCPproject_name
Near MRTREST–MCPmrt_stationsmrt_lines
Near a schoolREST–MCPschoolmax_school_distance_km
Floor areaREST–MCPsize_minsize_max
Price per sq ftREST–MCPpsf_minpsf_max
TenureREST–MCPtenure
Lease leftREST–MCPmin_remaining_lease_years
FurnishingREST–MCPfurnishing
Pets allowedREST–MCPpets_allowed
Utilities includedREST–MCPutilities_included
Open to foreignersREST–MCPforeign_tenant
Listed in the last daysREST–MCPlisted_within_days
Owner or agentREST–MCPlisted_by
Host reachable nowREST–MCPreachable_onlymessages_on_homejourney

Valuation widget

Show home value estimates on your website.

Visitors search an address, postal code or condo and get the same sale or rent estimate as the Homejourney valuation page, with recent comparable transactions. To build your own interface instead, call the valuation routes with a key holding valuations.read.

Paste where the widget should appear

<div data-homejourney-valuation data-embed-key="hje_test_your_widget_key"></div>
<script src="https://www.homejourney.sg/embed/valuation.js" async></script>
  • Create a widget key in the API Console under Valuation widget, listing each website that will show it as an exact origin such as https://www.example.com. A key works only on those websites.
  • Widget keys are publishable, not secrets: they identify your website and never authenticate the Platform API. Each key allows 2,000 estimates a day.
  • Add data-theme="dark" to the container on a dark page. The widget renders in its own shadow root, so your styles and its styles do not affect each other.
  • The widget is a Homejourney-branded panel. If your site sets a Content Security Policy, allow https://www.homejourney.sg in script-src, connect-src, img-src and font-src, which load its script, estimates, logo and fonts.
  • The estimate is free. The widget always shows "Estimate by Homejourney" with a link and the disclaimer.
  • Showing estimates means accepting the valuation partner terms, Part C of our Terms of Service: keep the attribution, no resale, keep an estimate no longer than 30 days, and no bulk collection.

Errors

What each error means, and how to fix it.

Errors are application/problem+json bodies with a code, a request_id and a type URL that opens the code’s entry below. Quote the request_id when you contact Homejourney support.

missing_authorization401

Missing authorization

Provide a bearer platform API key.

Send your API key as Authorization: Bearer <key> on every request.

invalid_authorization401

Invalid authorization

The bearer platform API key is malformed.

Use the form Authorization: Bearer <key>, with the whole key copied from the API Console and nothing else in the header.

environment_mismatch403

Environment mismatch

The API key is not valid for this platform environment.

Call the host that matches your key: hjp_test_ keys work on sandbox-platform-api.homejourney.sg, hjp_live_ keys on platform-api.homejourney.sg.

invalid_api_key401

Invalid API key

The API key is invalid or has not been issued.

Check the key was copied in full from the API Console. If it still fails, create a new key there.

inactive_api_key403

Inactive API key

The API key is revoked, expired, or inactive.

Create a new key in the API Console.

inactive_client403

Inactive integration client

The integration client is not active.

Check the client’s status in the API Console, or ask your organization’s admin.

inactive_organization403

Inactive organization

The platform organization is not active.

Contact Homejourney support.

insufficient_scope403

Missing required scope

The request is not authorized for this platform capability.

Add the scope this route needs to your API key in the API Console. The REST reference lists each route’s scope.

feature_not_available404

Feature not available

The platform API is not enabled for this organization.

Check your organization’s Platform API access in the API Console.

invalid_environment_host403

Invalid environment host

Use the sandbox or live platform API host for this credential.

Send sandbox keys to sandbox-platform-api.homejourney.sg and live keys to platform-api.homejourney.sg.

invalid_request400

Invalid request

The request body failed validation.

Compare the request body with the route’s schema in the REST reference and correct the fields it names.

missing_idempotency_key400

Missing idempotency key

Mutating platform requests require an Idempotency-Key header.

Add an Idempotency-Key header with a fresh unique value to each POST, PUT, PATCH or DELETE.

invalid_idempotency_key400

Invalid idempotency key

Idempotency-Key must be 8 to 128 characters using letters, numbers, dot, underscore, colon, or hyphen.

Use 8 to 128 letters, numbers, dots, underscores, colons or hyphens, such as a UUID.

idempotency_key_conflict409

Idempotency key conflict

The same Idempotency-Key was already used with a different request body.

Use a new Idempotency-Key for a different request. Reuse a key only to retry the exact same request.

idempotency_in_progress409

Idempotency key in progress

The same Idempotency-Key is already processing.

Wait a moment, then retry with the same key and the same body.

rate_limit_exceeded429

Rate limit exceeded

The platform API rate limit has been exceeded.

Slow down, and retry after the number of seconds in the Retry-After header.

not_found404

Not found

No platform API route matches this path. The REST reference at https://www.homejourney.sg/api-docs lists every route; GET /v1/organizations/current returns the organization your API key belongs to.

Check the path: every route starts with /v1/. The REST reference lists every route.

listing_not_found404

Listing not found

The listing was not found for this platform environment.

Check the listing id. Sandbox keys see only sandbox test listings, and live keys only live listings.

listing_feed_not_admitted403

Listing feed not admitted

The listing feed needs a live licensed estate agency organization with a linked feed source.

The listing feed is for licensed estate agencies. Apply for live access in the API Console, where review links your feed source.

salesperson_not_current422

Salesperson not current

The salesperson is not currently registered on the CEA public register.

Name a salesperson whose CEA registration is current. Check their number on the CEA public register.

salesperson_not_under_agency422

Salesperson not under agency

The salesperson is not registered under the agency's estate agent licence.

Name a salesperson registered under your agency’s estate agent licence on the CEA public register.

listing_validation_failed422

Listing validation failed

The listing could not be normalized for review.

Correct the listing fields the response names, then send it again.

review_queue_full429

Review queue full

The organization has the maximum number of listings waiting for review.

Wait for Homejourney to review your listings already in the queue, then send more.

site_not_found404

Partner site not found

The partner site was not found for this platform environment.

Check the site id belongs to your organization and to this environment.

developer_project_not_found404

Developer project not found

The developer project was not found for this platform environment.

Check the project id belongs to your organization and to this environment.

developer_showflat_slot_not_found404

Developer showflat slot not found

The developer showflat slot was not found for this platform environment.

List the project’s showflat slots and use one of their ids.

developer_showflat_slot_not_available409

Developer showflat slot not available

The developer showflat slot is not available for sandbox request creation.

Pick another slot from the project’s showflat slot list.

viewing_request_not_found404

Viewing request not found

The viewing request was not found for this platform environment.

Check the viewing request id belongs to your organization and to this environment.

service_booking_payment_status_not_found404

Service booking payment status not found

The service booking payment status was not found for this platform environment.

Check the booking id belongs to your organization and to this environment.

service_provider_payout_not_found404

Service-provider payout not found

The service-provider payout statement was not found for this platform environment.

Check the payout id belongs to your organization and to this environment.

renovation_project_not_found404

Renovation project not found

The Renovation project was not found for this platform environment.

Check the project id belongs to your organization and to this environment.

renovation_milestone_not_found404

Renovation milestone not found

The Renovation milestone was not found for this platform environment.

List the project’s milestones and use one of their ids.

renovation_milestone_version_conflict409

Renovation milestone version conflict

The Renovation milestone version has changed. Reload the milestone and retry.

Fetch the milestone again and resend your change with its current version.

bank_application_not_found404

Bank application not found

The bank application was not found for this platform environment.

Check the application id belongs to your organization and to this environment.

transaction_matter_not_found404

Transaction matter not found

The transaction matter was not found for this platform environment.

Check the matter id belongs to your organization and to this environment.

insurance_move_in_case_not_found404

Insurance or move-in coordination case not found

The sandbox insurance or move-in coordination case was not found.

Check the case id. This route works with sandbox cases only.

webhook_endpoint_not_found404

Webhook endpoint not found

The webhook endpoint was not found for this platform environment.

List your webhook endpoints and use one of their ids.

webhook_delivery_not_found404

Webhook delivery not found

The webhook delivery was not found for this platform environment.

List the endpoint’s deliveries and use one of their ids.

webhook_replay_not_available409

Webhook replay not available

Webhook replay is only available for sandbox deliveries with retained outbox payloads.

Replay works only for sandbox deliveries whose payload is still kept. Trigger a new event instead.

managed_webhook_subscription_not_found404

Managed webhook subscription not found

The managed webhook subscription was not found for this client and environment.

List your managed webhook subscriptions and use one of their ids.

managed_webhook_delivery_not_found404

Managed webhook delivery not found

The managed webhook delivery was not found for this client and environment.

List the subscription’s deliveries and use one of their ids.

managed_webhook_name_conflict409

Managed webhook name conflict

The immutable subscription name is already used by different desired configuration.

Give the new subscription a different name. A name cannot be reused for different settings.

managed_webhook_event_ineligible400

Managed webhook event is not eligible

One or more requested event types are not launch eligible for managed delivery.

Remove the event types the response names. The REST reference lists the events managed delivery supports.

managed_webhook_replay_not_available409

Managed webhook replay not available

The managed delivery does not satisfy every current replay prerequisite.

Check the delivery against the replay conditions in the REST reference, then try again.

managed_webhook_replay_quota_exceeded429

Managed webhook replay quota exceeded

The organization and environment replay quota has been exceeded.

Replay fewer deliveries. The quota counts your organization’s replays in this environment.

managed_webhook_subscription_quota_exceeded429

Managed webhook subscription quota exceeded

The organization and environment active subscription quota has been exceeded.

Delete a subscription you no longer use before creating another.

managed_webhook_secret_quota_exceeded429

Managed webhook secret version quota exceeded

The subscription retained secret version quota has been exceeded.

Retire an old signing secret before rotating to a new one.

managed_webhook_secret_unavailable503

Managed webhook secret custody unavailable

Managed webhook secret custody is temporarily unavailable.

Retry shortly. If it keeps failing, contact Homejourney support with the request_id.

provider_integration_app_not_found404

Provider integration app not found

The provider integration app was not found in the connected-app registry.

Check the app id against the connected apps in the API Console.

document_share_not_found404

Document share not found

The document share was not found for this platform environment and recipient.

Check the share id. You see only shares made to your organization in this environment.

agent_host_action_not_found404

Agent host action not found

The prepared agent host action was not found for this platform environment.

Check the action id belongs to your organization and to this environment.

agent_host_grant_not_found404

Agent host grant not found

The agent host grant was not found for this platform environment.

Check the grant id belongs to your organization and to this environment.

onboarding_gate_not_ready409

Onboarding gate not ready

The onboarding evidence gates do not yet allow this platform action.

Finish the onboarding steps the API Console shows for your organization, then try again.

valuation_engine_unavailable503

Valuations unavailable

Valuation estimates are temporarily unavailable.

Retry shortly. If it keeps failing, contact Homejourney support with the request_id.

valuation_embed_key_not_found404

Embed key not found

The valuation embed key was not found for this organization and environment.

List your embed keys and use one of their ids.

valuation_embed_key_quota_exceeded429

Embed key quota exceeded

The organization and environment already hold the maximum number of active embed keys.

Revoke an embed key you no longer use before creating another.

missing_scope403

Missing required scope

The request is not authorized for this platform capability.

Add the scope this route needs to your API key in the API Console. The REST reference lists each route’s scope.

internal_error500

Internal Server Error

The platform API request failed.

Retry the request. If it keeps failing, contact Homejourney support with the request_id.

Ready to go deeper?

Explore every operation.

The interactive reference is generated from the OpenAPI contract every platform route follows, so any OpenAPI tool can generate a client from it.

Open REST API reference (opens in a new tab)