GET
/
api
/
v1
/
onboarding
/
landlords
Landlord autocomplete
curl --request GET \
  --url https://api.example.com/api/v1/onboarding/landlords
import requests

url = "https://api.example.com/api/v1/onboarding/landlords"

response = requests.get(url)

print(response.text)
const options = {method: 'GET'};

fetch('https://api.example.com/api/v1/onboarding/landlords', 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/landlords",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);

$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/landlords"

req, _ := http.NewRequest("GET", url, nil)

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/onboarding/landlords")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/onboarding/landlords")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

Overview

Returns the curated list of UK councils and housing associations the client offers as autocomplete suggestions on the step-1 “Who is your landlord?” tenancy form. This is a reference lookup only — it does not verify anything; a human admin reviews the uploaded tenancy document. Pass an optional q to filter by name as the user types, and an optional type to restrict to councils or housing associations. Only active landlords are returned, name-sorted, capped at 20 rows. The list is populated by the pnpm seed:landlords script (a vendored data file mirroring the Regulator of Social Housing register — ~1,580 councils + private registered providers) and curated by admins via the admin landlords endpoints. When the user’s landlord is not in the list, the client falls back to the free-text landlordName field on step 1 with landlordId: null.

Authentication

Bearer <accessToken> required. Scope: user.

Path parameters

None.

Query parameters

ParamTypeRequiredNotesExample
qstringnoCase-insensitive substring match on the landlord name (1..100 chars).camden
typestringnoFilter to COUNCIL or HOUSING_ASSOCIATION.COUNCIL

Request body

None.

Response — 200 OK

FieldTypeNotesExample
itemsarrayUp to 20 active landlords matching the query, name-sorted. Empty when nothing matches or the list is unseeded in this environment.see below
items[].idstringLandlord id — send back as landlordId on step 1.665f0a...
items[].namestringCanonical landlord name.London Borough of Camden
items[].typestringCOUNCIL or HOUSING_ASSOCIATION.COUNCIL

Example response

{
  "items": [
    { "id": "665f0a1b2c3d4e5f60718293", "name": "London Borough of Camden", "type": "COUNCIL" }
  ]
}

Error responses

StatusCodeMeaning
400VALIDATION_FAILEDtype is not one of the allowed values, or q is out of range.
401UNAUTHENTICATEDMissing, malformed, or expired access token.

Side effects

None — this is a pure read.

See also

curl

# All councils matching "camden"
curl -X GET "https://api.swappr.co.uk/api/v1/onboarding/landlords?q=camden&type=COUNCIL" \
  -H "Authorization: Bearer $ACCESS_TOKEN"