POST
/
api
/
v1
/
admin
/
tenancy
/
:id
/
approve
Approve tenancy verification
curl --request POST \
  --url https://api.example.com/api/v1/admin/tenancy/:id/approve
import requests

url = "https://api.example.com/api/v1/admin/tenancy/:id/approve"

response = requests.post(url)

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

fetch('https://api.example.com/api/v1/admin/tenancy/:id/approve', 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/admin/tenancy/:id/approve",
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/admin/tenancy/:id/approve"

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/admin/tenancy/:id/approve")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/admin/tenancy/:id/approve")

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_body

Overview

Approves a tenancy verification. In one operation it:
  1. Updates the verification row (reviewStatus = APPROVED, reviewedBy, reviewedAt).
  2. Flips users.tenancyStatus → APPROVED.
  3. Denormalises ownerTenancyApproved = true onto the user’s active current-home listing (this is what lets the listing count toward the live-listing total).
  4. Enqueues the tenancy.approved push notification and the approval email (Phase 5 fan-out — see Push notification fan-out).
Idempotent: re-approving an already-APPROVED row is a no-op (no duplicate push/email).

Authentication

Bearer <accessToken> with scope: 'admin' required (requireAdmin).
Role-gated: requires SUPER or MODERATOR. A FINANCE admin receives 403 FORBIDDEN.

Path parameters

NameTypeRequiredNotesExample
idstringyesVerification row ObjectId, 1..64 chars.66400a8f1c2b4d5e6f7ab000

Query parameters

None.

Request body

None.

Response — 200 OK

Returns the updated tenancy verification row with reviewStatus: "APPROVED".
{
  "id": "66400a8f1c2b4d5e6f7ab000",
  "userId": "66400a8f1c2b4d5e6f7a8b01",
  "landlordName": "Acme Lettings",
  "documentType": "TENANCY_AGREEMENT",
  "uploadId": "66400a8f1c2b4d5e6f7ac000",
  "reviewStatus": "APPROVED",
  "reviewedBy": "66400a8f1c2b4d5e6f7a0001",
  "reviewedAt": "2026-05-23T11:10:00.000Z",
  "reviewNotes": null,
  "createdAt": "2026-05-20T08:30:00.000Z",
  "user": { "id": "66400a8f1c2b4d5e6f7a8b01", "email": "jane@example.com", "firstName": "Jane", "lastName": "Doe" },
  "upload": null,
  "documentDownloadUrl": null
}

Error responses

StatusCodeMeaning
401UNAUTHENTICATEDMissing, malformed, expired, or non-admin-scope token.
403FORBIDDENCaller is a FINANCE admin.
404NOT_FOUNDNo verification row with that id.
409STATE_CONFLICTRow is already REJECTED — a rejected verification cannot be flipped to approved through this endpoint.

Example error — 409 STATE_CONFLICT

{
  "type": "https://api.swappr.co.uk/errors/state-conflict",
  "title": "State conflict",
  "status": 409,
  "code": "STATE_CONFLICT",
  "detail": "Verification is already rejected",
  "instance": "/api/v1/admin/tenancy/66400a8f1c2b4d5e6f7ab000/approve",
  "requestId": "01HZQ7K3M4N5P6Q7R8S9T0V1W2"
}

Side effects

  • Verification row + users.tenancyStatus updated.
  • ownerTenancyApproved denormalised onto the active listing.
  • tenancy.approved push job + approval email enqueued (best-effort; failures do not roll back the approval).
  • Audit-log row written (action tenancy.approve).

See also

curl

curl -X POST https://api.swappr.co.uk/api/v1/admin/tenancy/66400a8f1c2b4d5e6f7ab000/approve \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"

Postman

See docs/postman/swappr.postman_collection.jsonAdmin Tenancy → Approve.