GET
/
api
/
v1
/
matches
/
{matchId}
Get match detail
curl --request GET \
  --url https://api.example.com/api/v1/matches/{matchId}
import requests

url = "https://api.example.com/api/v1/matches/{matchId}"

response = requests.get(url)

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

fetch('https://api.example.com/api/v1/matches/{matchId}', 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/matches/{matchId}",
  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/matches/{matchId}"

	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/matches/{matchId}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/matches/{matchId}")

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 full detail for a single match — everything the Property Detail screen needs: the other user’s listing (with description), their housing provider, what they’re looking for, and the per-filter match flags. The property, peer, housingProvider, and theyWant blocks are all relative to the other participant (never the caller). Returns 404 NOT_FOUND if the match does not exist or if the caller is not a participant — existence is never leaked.

​
Authentication

Bearer <accessToken> required. Scope: user. Requires completed onboarding + approved tenancy (requireOnboarded).

​
Path parameters

ParamTypeNotes
matchIdstring24-char ObjectId of the match. 400 if malformed.

​
Query parameters

None.

​
Request body

None.

​
Response — 200 OK

FieldTypeNotes
matchobjectSee Match detail object.

​
Match detail object

All Match summary fields (matchId, score, perfectMatch, matchTier, savedAt, peer, property) plus:
FieldTypeNotes
property.descriptionstringThe listing’s free-text description (0..150 chars).
housingProviderstring | nullThe other user’s latest tenancy verification landlordName. null if they have no tenancy record.
theyWantobjectThe other user’s preferences — “What They’re Looking For”. See theyWant object.
hardFilterFlagsobjectPer-filter pass/fail for this pair: { propertyType, bedrooms, rent, distance, eligibility, blocks } (all booleans).

​
theyWant object

FieldTypeNotes
desiredPropertyTypesstring[]Subset of the property-type enum.
minBedroomsinteger0..10.
maxBedroomsinteger0..10.
maxRentMonthlyMinorintegerServer-derived monthly pence cap.
preferredLocationsobject[]{ label, postcode, lng, lat }. postcode may be null.
searchRadiusMilesintegerOne of 0, 1, 3, 5, 10, 25.
desiredFeaturesstring[]Subset of the feature enum.

​
Example response

{
  "match": {
    "matchId": "66400a8f1c2b4d5e6f7a8e00",
    "score": 88,
    "perfectMatch": false,
    "matchTier": "GREAT",                             // enum: "PERFECT" | "GREAT" | "GOOD"
    "savedAt": null,
    "peer": { "id": "66400a8f1c2b4d5e6f7a8b02", "firstName": "Sam" },
    "property": {
      "id": "66400a8f1c2b4d5e6f7a8c02",
      "propertyType": "FLAT",
      "bedrooms": 2,
      "bathrooms": 1,
      "address": "9 Peer Road, London",
      "postcode": "E1 6AN",
      "location": { "lng": -0.0712, "lat": 51.5176 },
      "rent": { "amountMinor": 150000, "frequency": "MONTHLY" },
      "rentMonthlyMinor": 150000,
      "features": ["GARDEN"],
      "photos": [
        {
          "id": "66400a8f1c2b4d5e6f7a8d10",
          "url": "https://cdn.swappr.co.uk/listings/.../01.jpg",
          "thumbnailUrl": "https://cdn.swappr.co.uk/listings/.../01.jpg",
          "orderIndex": 0,
          "isCover": true,
          "blurhash": "L6PZfSi_.AyE_3t7t7R**0o#DgR4",
          "width": 1600,
          "height": 1200
        }
      ],
      "description": "Bright 2-bed flat near the canal, recently refurbished kitchen, south-facing balcony."
    },
    "housingProvider": "Camden Council",                 // peer's latest tenancy landlordName, or null
    "theyWant": {
      "desiredPropertyTypes": ["FLAT", "TERRACED"],
      "minBedrooms": 1,
      "maxBedrooms": 3,
      "maxRentMonthlyMinor": 200000,
      "preferredLocations": [
        { "label": "Camden", "postcode": "NW1 6XE", "lng": -0.1276, "lat": 51.5074 }
      ],
      "searchRadiusMiles": 5,
      "desiredFeatures": ["GARDEN"]
    },
    "hardFilterFlags": {
      "propertyType": true,
      "bedrooms": true,
      "rent": true,
      "distance": true,
      "eligibility": true,
      "blocks": true
    }
  }
}

​
Error responses

StatusCodeMeaning
400VALIDATION_FAILEDmatchId is not a 24-char ObjectId.
401UNAUTHENTICATEDMissing, malformed, or expired access token.
404NOT_FOUNDNo such match, or the caller is not a participant (existence is not leaked).

​
Example error — 404

{
  "type": "https://api.swappr.co.uk/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "code": "NOT_FOUND",
  "detail": "Match not found",
  "instance": "/api/v1/matches/66400a8f1c2b4d5e6f7a8e00",
  "requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}

​
Side effects

None — this is a pure read.

​
See also

​
curl

curl -X GET https://api.swappr.co.uk/api/v1/matches/66400a8f1c2b4d5e6f7a8e00 \
  -H "Authorization: Bearer $ACCESS_TOKEN"