Tenancy & Referencing Management

An application is the tenancy. Applicants are tenants and guarantors on that tenancy. Adding an applicant creates them with status Created; referencing starts once their details are submitted, either by the applicant through the form BOX emails them, or by you through the API.

sequenceDiagram
  autonumber
  actor CRM
  participant API as Lettings Hub
  CRM->>API: POST /Applications/BranchId
  API-->>CRM: 200, application reference
  CRM->>API: POST .../Tenants
  API-->>CRM: 200, tenant created
  CRM->>API: POST .../Tenants/TenantRef
  API-->>CRM: 200, tenant submitted
  API->>CRM: POST webhook
  CRM->>API: GET .../Reports/ReportType
  API-->>CRM: 200, PDF

Usual sequence. Enable agent webhooks before submit if you want the report-ready callback.

1. Create the tenancy

POST /Applications/{BranchId}. The 200 body is the application reference as a JSON string. Store it; later paths use {ApplicationRef} or {ReferenceNumber}.

{
  "ExternalReference": "CRM-88421",
  "RentalDetails": {
    "MonthlyRent": 1250,
    "BillsIncludedWithinTheRent": false,
    "TenancyTerm": 12,
    "TenancyStartDate": "2026-09-01",
    "HowWillTheProperyBeManaged": 3,
    "RentalFrequency": 1
  },
  "PropertyInformation": {
    "IsLandlordKnown": true,
    "IsHMO": false,
    "NumberOfBedrooms": 2,
    "Address": {
      "Postcode": "BA13 3BN",
      "HouseNumber": "12",
      "Street": "High Street",
      "Town": "Westbury",
      "County": "Wiltshire",
      "Country": "United Kingdom"
    }
  },
  "InviteLandlordForAMLCheck": false,
  "ReferenceRequired": true
}

Example create-tenancy body. HowWillTheProperyBeManaged: 3 is Managed. RentalFrequency: 1 is monthly. Codes are listed under Dictionaries. Field names match the spec, including HowWillTheProperyBeManaged.

2. Add the tenant

POST /Applications/{ApplicationRef}/Tenants uses the CreateTenant schema. The 200 body is an Applicant including ReferenceNumber for the tenant. The tenant now exists with status Created; referencing has not started.

{
  "Title": 3,
  "FirstName": "Jane",
  "LastName": "Cole",
  "EmailAddress": "jane.cole@example.com",
  "ReportType": 5,
  "ShareOfRent": 1250,
  "RentCoveredByOtherTenant": false,
  "IsIncomeReferenceRequired": true,
  "IdentityCheck": {
    "IdVerification": true,
    "RightToRentVerification": true,
    "AMLVerification": false,
    "PEPsAndSanctionsVerification": false
  }
}

Example body. Title 3 is Miss. ReportType 5 is Essential. State is only needed when Title is 10 (Other).

Then decide who completes the referencing form, with IsApplicantFillingTheForm on this call:

The tenant completes it. Set it to true. BOX emails the tenant an invitation and chases them until they finish; referencing starts when they submit. Skip step 3.
You submit their details. Leave it false (the default) and go on to step 3. Until you do, BOX chases the branch to complete the form.

Guarantors work the same way: POST …/Guarantors to add, POST …/Guarantors/{GuarantorRef} to submit.

3. Submit the tenant's details

POST /Applications/{ApplicationRef}/Tenants/{TenantRef} uses the full Applicant schema. Date of birth, nationality, marital status, address history, income evidence and signed consent are required at this point even if they were omitted on create.

{
  "Title": 3,
  "FirstName": "Jane",
  "LastName": "Cole",
  "IsNameLegal": true,
  "EmailAddress": "jane.cole@example.com",
  "BestPhoneNumber": "07700900000",
  "ReportType": 5,
  "ShareOfRent": 1250,
  "RentCoveredByOtherTenant": false,
  "IsIncomeReferenceRequired": true,
  "IsApplicantFillingTheForm": false,
  "BirthDay": "1992-04-25",
  "Nationality": "British",
  "MaritalStatus": 7,
  "AnyPreviousSurnames": false,
  "HasInsuranceNo": true,
  "InsuranceNo": "AB123456C",
  "HasAdverceData": false,
  "IdentityCheck": {
    "IdVerification": true,
    "RightToRentVerification": true,
    "AMLVerification": false,
    "PEPsAndSanctionsVerification": false
  },
  "AddressHistory": [
    {
      "DateMovedIn": "2020-01-15",
      "LivingStatus": 1,
      "Address": {
        "Postcode": "BA13 3BN",
        "HouseNumber": "12",
        "Street": "High Street",
        "Town": "Westbury",
        "County": "Wiltshire",
        "Country": "United Kingdom"
      }
    }
  ],
  "SignedConsent": {
    "DeliveryMethod": 1
  }
}

Example submit body (income evidence omitted for length). MaritalStatus 7 is Single. LivingStatus 1 is Owner. DeliveryMethod 1 is Upload. If you already have the full payload, POST …/CompletedTenants creates and submits in one call.

The OpenAPI required array on Applicant lists submit-time fields. The body in step 2 can omit them; follow the per-field “optional on create / mandatory on submit” notes in the reference.

4. Reports

GET …/Reports returns available report type ids. GET …/Reports/{ReportType} returns application/pdf.

Id	Product
1	Elite
3	Interim
5	Essential
6	Upgraded to Elite
7	Summary
8	Essential+
9	Essential++

Other calls

PUT …/RentShare — body is [{"ApplicantRef":"…","Rent":625}]
PUT …/TenancyStartDate/{TenancyStartDate} — ISO date in the path
POST …/CancelTenancy/{ApplicantRef} — body is a reason string
GET …/Notes and GET …/AuditTrail