Onboarding step 4 — desired home
curl --request POST \
--url https://api.example.com/api/v1/onboarding/step-4-desired-homeimport requests
url = "https://api.example.com/api/v1/onboarding/step-4-desired-home"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/onboarding/step-4-desired-home', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/onboarding/step-4-desired-home",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/onboarding/step-4-desired-home"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/onboarding/step-4-desired-home")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/onboarding/step-4-desired-home")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyOnboarding
Onboarding step 4 — desired home
Submit matching preferences. Completes onboarding. Step 4 of 4.
POST
/
api
/
v1
/
onboarding
/
step-4-desired-home
Onboarding step 4 — desired home
curl --request POST \
--url https://api.example.com/api/v1/onboarding/step-4-desired-homeimport requests
url = "https://api.example.com/api/v1/onboarding/step-4-desired-home"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/api/v1/onboarding/step-4-desired-home', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/onboarding/step-4-desired-home",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/onboarding/step-4-desired-home"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/v1/onboarding/step-4-desired-home")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/onboarding/step-4-desired-home")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyOverview
Submits the user’s matching preferences (the “desired home” filter) and completes onboarding. After a successful call:user_preferencesis persisted (full replace).users.onboardingStatus = COMPLETEandusers.currentStep = null.- A
tenancy.reviewjob is enqueued (admin queue gate — Phase 6 will consume it). - A
match.recomputejob is enqueued (Phase 3 will consume it).
409 STATE_CONFLICT. Further preferences edits go through PUT /preferences/me; further listing edits through /current-home/me/*.
Preconditions:
currentStepis exactly4.
Authentication
Bearer <accessToken> required. Scope: user.
Path parameters
None.Query parameters
None.Request body
| Field | Type | Required | Allowed values / Constraints | Example |
|---|---|---|---|---|
desiredPropertyTypes | string[] | yes | Non-empty array of: DETACHED, SEMI_DETACHED, TERRACED, FLAT, MAISONETTE, BUNGALOW, STUDIO | ["FLAT", "MAISONETTE"] |
minBedrooms | integer | yes | 0..10 inclusive. Must be <= maxBedrooms. | 1 |
maxBedrooms | integer | yes | 0..10 inclusive. Must be >= minBedrooms. | 3 |
maxRent | object | yes | See MaxRent object. | |
preferredLocations | object[] | yes | 1..5 entries. See PreferredLocation object. | |
searchRadiusMiles | number | yes | One of: 0, 1, 3, 5, 10, 25. (0 means “exact postcode only”.) | 5 |
desiredFeatures | string[] | no | Subset of: GARDEN, PARKING, BALCONY, LIFT, GROUND_FLOOR, PETS_ALLOWED, WHEELCHAIR_ACCESS, NEW_BUILD. Defaults to []. | ["BALCONY"] |
MaxRent object
| Field | Type | Required | Notes / Constraints | Example |
|---|---|---|---|---|
amountMinor | integer | yes | Positive integer pence. | 150000 |
frequency | enum | yes | WEEKLY, MONTHLY | MONTHLY |
PreferredLocation object
| Field | Type | Required | Notes / Constraints | Example |
|---|---|---|---|---|
label | string | yes | 1..200 chars. Human-readable area name. | Camden, London |
lng | number | yes | -180..180. Decimal degrees, WGS-84. | -0.1426 |
lat | number | yes | -90..90. Decimal degrees, WGS-84. | 51.5390 |
postcode | string | null | yes | 1..16 chars, or null when the user selected an area rather than a postcode. | NW1 7JE |
Example payload
{
"desiredPropertyTypes": [
"FLAT", // enum (multi): "DETACHED" | "SEMI_DETACHED" | "TERRACED" | "FLAT" | "MAISONETTE" | "BUNGALOW" | "STUDIO"
"MAISONETTE"
],
"minBedrooms": 1, // integer 0..10
"maxBedrooms": 3, // integer 0..10
"maxRent": {
"amountMinor": 150000, // integer pence; 150000 = £1,500.00
"frequency": "MONTHLY" // enum: "WEEKLY" | "MONTHLY"
},
"preferredLocations": [
{
"label": "Camden, London",
"lng": -0.1426,
"lat": 51.5390,
"postcode": "NW1 7JE" // string | null
}
],
"searchRadiusMiles": 5, // enum: 0 | 1 | 3 | 5 | 10 | 25
"desiredFeatures": [
"BALCONY" // enum (multi): "GARDEN" | "PARKING" | "BALCONY" | "LIFT" | "GROUND_FLOOR" | "PETS_ALLOWED" | "WHEELCHAIR_ACCESS" | "NEW_BUILD"
]
}
Response — 200 OK
Returns the refreshed onboarding state.onboardingStatus flips to COMPLETE and currentStep becomes null.
| Field | Type | Allowed values | Example |
|---|---|---|---|
onboardingStatus | enum | becomes COMPLETE | COMPLETE |
currentStep | integer | null | becomes null | null |
tenancyStatus | enum | unchanged from step-1 submission | PENDING |
Example response
{
"onboardingStatus": "COMPLETE",
"currentStep": null,
"tenancyStatus": "PENDING" // enum: "NOT_SUBMITTED" | "PENDING" | "APPROVED" | "REJECTED"
}
Error responses
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | Body fails Zod validation, including the minBedrooms <= maxBedrooms cross-field check or an unsupported searchRadiusMiles. |
| 401 | UNAUTHENTICATED | Missing, malformed, or expired access token. |
| 409 | STATE_CONFLICT | currentStep is not 4, or onboarding is already complete. |
Example error — 400
{
"type": "https://api.swappr.co.uk/errors/validation-failed",
"title": "Validation failed",
"status": 400,
"code": "VALIDATION_FAILED",
"detail": "Request body failed validation",
"instance": "/api/v1/onboarding/step-4-desired-home",
"requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2",
"errors": [
{ "path": "minBedrooms", "message": "minBedrooms must be <= maxBedrooms", "code": "custom" }
]
}
Side effects
- Upserts the caller’s row in the
user_preferencescollection (maxRentMonthlyMinoris derived server-side). - Sets
users.onboardingStatus = COMPLETE,users.currentStep = null, and stampsonboardingCompletedAt. - Enqueues a
tenancy.reviewjob for the admin review queue (consumed in Phase 6) when atenancyVerificationIdexists. - Enqueues a
match.recomputejob (consumed in Phase 3) withreason: 'preferences_updated'.
See also
- Get my preferences
- Replace my preferences
- Publish listing — requires
tenancyStatus = APPROVED. - Onboarding state machine
curl
curl -X POST https://api.swappr.co.uk/api/v1/onboarding/step-4-desired-home \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"desiredPropertyTypes": ["FLAT", "MAISONETTE"],
"minBedrooms": 1,
"maxBedrooms": 3,
"maxRent": { "amountMinor": 150000, "frequency": "MONTHLY" },
"preferredLocations": [
{ "label": "Camden, London", "lng": -0.1426, "lat": 51.5390, "postcode": "NW1 7JE" }
],
"searchRadiusMiles": 5,
"desiredFeatures": ["BALCONY"]
}'