Referencing

An application is the tenancy. Applicants are tenants and guarantors on that tenancy. Creating an applicant stores a draft; submitting it starts referencing. The two calls use different payloads.

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 draft
  CRM->>API: POST .../Tenants/TenantRef
  API-->>CRM: 200, tenant submitted
  API->>CRM: POST webhook or notification
  CRM->>API: GET .../Reports/ReportType
  API-->>CRM: 200, PDF

Usual sequence. Enable agent webhooks or register notifications 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. Create a tenant (draft)

POST /Applications/{ApplicationRef}/Tenants uses the CreateTenant schema. The 200 body is an Applicant including ReferenceNumber for the tenant.

{
  "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 draft. Title 3 is Miss. ReportType 5 is Essential. State is only needed when Title is 10 (Other).

Guarantors: POST …/Guarantors to draft, POST …/Guarantors/{GuarantorRef} to submit.

3. Submit the tenant

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. A create-draft body 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