NAV

Introduction

BASE URL

https://your_council.metastreet.co.uk/api/v1.1/
The Metastreet API is organised around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

EXAMPLE AUTHENTICATED REQUEST

$ curl 'https://your_council.metastreet.co.uk/api/v1.1/properties' \
-H 'x-auth-api-token: 3b07c593c309ebf41330cd6f6867610eb18abe43dcf1d'

EXAMPLE RESPONSE

{
  "object": "property",
  "url": "/api/v1.1/properties",
  ...
  "data": [ {
    "id": 1248196,
    "referenceNumbers": [
      "YCO-583484913397"
    ],
    "address": {
      "addressLine1": "4 Dasher Place",
      "addressLine2": "Dasher Street",
      "addressLine3": "Dasher Estate",
      ...
    }
    ...
  },
  ]
}

The Metastreet API uses API keys to authenticate requests. You can view your API key(s) in Settings -> Integrations section of the council backend. If you can't find your API key(s), please contact your account manager.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All requests to our API must include your API key in the x-auth-api-token header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Response codes

EXAMPLE ERROR MESSAGE

http code 404
{
  "error": "Invalid endpoint"
}

Metastreet uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Metastreet's servers (these are rare).

Response Code Meaning
200 OK -- Everything worked as expected
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
402 Request failed -- The parameters were valid but the request failed.
403 Forbidden -- The API key doesn't have permissions to perform the request.
404 Not Found -- The requested resource doesn't exist.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't available.
410 Gone -- The resource requested has been removed from our servers.
429 Too Many Requests -- Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Pagination

EXAMPLE PAGINATION REQUEST

$ curl 'https://your_council.metastreet.co.uk/api/v1.1/properties?pageSize=50&page=4' \
-H 'x-auth-api-token: 3b07c593c309ebf41330cd6f6867610eb18abe43dcf1d'

EXAMPLE RESPONSE

{
  "object": "property",
  "url": "https://your-council.metastreet.co.uk/api/v1/properties",
  "pageSize": 50,
  "currentPage": 4,
  "totalPages": 9,
  "totalCount": 401,
  "data": [
    {
      "id": 1248196,
      "referenceNumbers": [
        "YCO-583484913397"
      ],
      "address": {
        "addressLine1": "4 Dasher Place",
        "addressLine2": "Dasher Street",
        "addressLine3": "Dasher Estate",
        ...
      }
    }
    ...
  ]
}

All top-level API resources have support for pagination.

The pageSize and page query parameters let you control pagination.

One page is returned per request. Using the pageSize parameter, you can define the number of items to be displayed on this page - the default is 100 items.

Using the page parameter you can select which page you would like to be returned.

To set the pageSize and page parameters, you should pass a value greater than 0 as a query argument.

CORE RESOURCES

Properties

ENDPOINTS

  GET /properties
  GET /properties/:uprn
Provides top level property data including address, UPRN, USRN and reference numbers of any licences, applications and temporary exemptions associated with the property.

The property object

THE PROPERTY OBJECT

{
  "id": 1248196,
  "referenceNumbers": [
    "YCO-583484913397"
  ],
  "address": {
    "addressLine1": "4 Dasher Place",
    "addressLine2": "Dasher Street",
    "addressLine3": "Dasher Estate",
    "addressLine4": "Dasher",
    "city": "London",
    "country": "United Kingdom",
    "county": "Greater London",
    "postcode": "A1 2BC",
    "uprn": "12345678910",
    "usrn": "1234567",
    "latitude": "1.230045",
    "longitude": "-5.430021",
    "ward": "Dasher Ward"
  }
}

Attributes

id string

Unique identifier for the object.

referenceNumbers array

List of reference numbers of any licences, applications and temporary exemptions associated with the property.

address object

All address data.

address.addressLine1 string

First line of the property's address.

address.addressLine2 string

Second line of the property's address.

address.addressLine3 string

Third line of the property's address.

address.addressLine4 string

Fourth line of the property's address.

address.city string

City of the address.

address.country string

Country of the address.

address.county string

County of the address.

address.postcode string

Postcode of the address.

address.uprn string

Unique Property Reference Number (UPRN) of the address.

address.usrn string

Unique Street Reference Number (USRN) of the address.

address.latitude string

Latitude of the address in decimal degrees (ISO 6709).

address.longitude string

Longitude of the address in decimal degrees (ISO 6709).

address.ward string

Ward of the address.

List all properties

GET /properties

$ curl 'https://your_council.metastreet.co.uk/api/v1.1/properties?postcode=A12BC' \
-H 'x-auth-api-token: 3b07c593c309ebf41330cd6f6867610eb18abe43dcf1d'

EXAMPLE RESPONSE

{
  "object": "property",
  "url": "/api/v1.1/properties",
  "pageSize": 100,
  "currentPage": 1,
  "totalPages": 1,
  "totalCount": 45,
  "data": [
    {
      "id": 1248196,
      "referenceNumbers": [
        "YCO-583484913397"
      ],
      "address": {
        "addressLine1": "4 Dasher Place",
        "addressLine2": "Dasher Street",
        "addressLine3": "Dasher Estate",
        "addressLine4": "Dasher",
        "city": "London",
        "country": "United Kingdom",
        "county": "Greater London",
        "postcode": "A1 2BC",
        "uprn": "12345678910",
        "usrn": "1234567",
        "latitude": "1.230045",
        "longitude": "-5.430021",
        "ward": "Dasher Ward"
      }
    }
    ...
  ]
}
Returns a list of your properties. The properties are returned sorted by uprn, with the properties with the lowest uprn appearing first.

Parameters

postcode optional

A filter on the list based on the property’s postcode field. The value must be a string. The filter is not case-sensitive and spaces can removed.

Pagination parameters are also available - see Pagination.

Returns

A dictionary with a data property that contains an array of properties. Passing an optional postcode will result in filtering to properties with only that exact postcode. Each entry in the array is a separate property object. If no more properties are available, the resulting array will be empty. This request should never return an error.

Retrieve a property

GET /properties/:uprn

$ curl 'https://your_council.metastreet.co.uk/api/v1.1/properties/10008223635' \
-H 'x-auth-api-token: 3b07c593c309ebf41330cd6f6867610eb18abe43dcf1d'

EXAMPLE RESPONSE

{
  "object": "property",
  "url": "/api/v1.1/properties",
  "data": [
    {
      "id": 1248196,
      "referenceNumbers": [
        "YCO-583484913397"
      ],
      "address": {
        "addressLine1": "4 Dasher Place",
        "addressLine2": "Dasher Street",
        "addressLine3": "Dasher Estate",
        "addressLine4": "Dasher",
        "city": "London",
        "country": "United Kingdom",
        "county": "Greater London",
        "postcode": "A1 2BC",
        "uprn": "10008223635",
        "usrn": "1234567",
        "latitude": "1.230045",
        "longitude": "-5.430021",
        "ward": "Dasher Ward"
      }
    }
    ...
  ]
}
Retrieves a Property object.

Parameters

No parameters.

Returns

Returns the Property object for a valid identifier.

Licences

ENDPOINTS

  GET /licences
  GET /licences/:referenceNo
This object represents a property licence or licence application.
It includes data about the property (rooms, health and safety information, occupancy) and interested parties. It also provides metadata pertaining to the processing of the licence application including licence phase/type/status, issue dates and staff assignees.

The licence object

THE LICENCE OBJECT

{
  "referenceNumber": "YCO-583484913397",
  "address": {
    "addressLine1": "4 Dasher Place",
    "addressLine2": "Dasher Street",
    "addressLine3": "Dasher Estate",
    "addressLine4": "Dasher",
    "city": "London",
    "country": "United Kingdom",
    "county": "Greater London",
    "postcode": "A1 2BC",
    "uprn": "12345678910",
    "usrn": "1234567",
    "latitude": "1.230045",
    "longitude": "-5.430021",
    "ward": "Dasher Ward"
  },
  "licencePhase": "Application",
  "licenceType": {
    "id": 3,
    "name": "Selective licence"
  },
  "licenceStatus": {
    "id": 12,
    "name": "Checks in progress"
  },
  "assignee": {
    "id": 7,
    "name": "Council Admin"
  },
  "dateSubmitted": "2021-11-26T09:32:08+00:00",
  "datePaid": "2021-11-26T09:32:08+00:00",
  "propertyRooms": {
    "bathrooms": [
      {
        "location": "First floor rear",
        "exclusivity": "Shared",
        "washHandBasins": 1,
        "toilets": 1,
        "bathsAndShowers": 2
      }
    ],
    "bedrooms": [
      {
        "location": "First floor front",
        "size": 12.59,
        "exclusivity": "Exclusive",
        "bathroomFacilities": "Yes",
        "washBasins": 1,
        "toilets": 0,
        "bathShower": 1,
        "kitchenFacilities": "No",
        "ovens": 0,
        "hobs": 0,
        "sinks": 0,
        "fridges": 0,
        "freezers": 0
      },
      {
        "location": "First floor rear",
        "size": 26.1,
        "exclusivity": "Shared",
        "bathroomFacilities": "No",
        "washBasins": 0,
        "toilets": 0,
        "bathShower": 0,
        "kitchenFacilities": "Yes",
        "ovens": 1,
        "hobs": 1,
        "sinks": 1,
        "fridges": 1,
        "freezers": 1
      }
    ],
    "communalRooms": [
      {
        "location": "Ground floor north side",
        "size": 45.0,
        "exclusivity": "Shared",
        "smokeAlarm": "Yes",
        "bestDescription": "Living room",
        "washHandBasins": 0
      }
    ],
    "kitchens": [
      {
        "location": "Ground floor rear",
        "size": 15.45,
        "exclusivity": "Shared",
        "smokeAlarm": "Yes",
        "ovens": 1,
        "hobs": 1,
        "sinks": 1,
        "fridges": 1,
        "freezers": 1
      }
    ]
  },
  "propertyUnits": {
    "unitsNotUnderLicenceHolder": [
      {
        "name": "56",
        "floor": "5th",
        "occupied": "Privately rented"
      }
    ],
    "flatsUnderLicenceHolder": [
      {
        "name": "57",
        "floor": "5th",
        "entrance": "Shared",
        "roomsInFlat": 3,
        "tenancyType": "Assured shorthold tenancy (AST)",
        "occupiersCount": 2
      }
    ],
    "bedsitsUnderLicenceHolder": [
      {
        "name": "58",
        "floor": "5th",
        "entrance": "Shared",
        "size": 68.0,
        "tenancyType": "Regulated tenancy",
        "occupiersCount": 2
      }
    ]
  },
  "eligibilityInformation": {
    "unspentConvictions": "Yes",
    "unspentConvictionsDetails": "Details about unspent convictions.",
    "unlawfulDiscrimination": "Yes",
    "unlawfulDiscriminationDetails": "Details about unlawfaul discrimination.",
    "judgementMadeAgainstYou": "Yes",
    "judgementMadeAgainstYouDetails": "Details about judgements made against you.",
    "experienceOfManagingRentedProperty": "Yes",
    "licenceHolderBelongToLandlords": "Yes",
    "nameOfAssociation": "Name of Landlord Association",
    "registrationNumber": "LA-33234432",
    "propertyVisited": "Yes",
    "hasFunds": "Yes",
    "fundsInfo": "£1000 per month.",
    "hasPropertyInControlToManagementOrder": "Yes",
    "hasPropertyInControlToManagementOrderDetails": "Details about Management Order.",
    "hasPropertyThatHasBeenRefused": "Yes",
    "hasPropertyThatHasBeenRefusedDetails": "Details about being refused a licence.",
    "regularInspection": "Yes",
    "regularInspectionMonthly": 2,
    "regularInspectionPerson": "Planet Property",
    "regularCleaning": "Yes",
    "regularCleaningMonthly": 2,
    "regularCleaningPerson": "OSF Cleaning",
    "problems": "Yes",
    "problemsDetails": "Details of any problems."
  },
  "healthAndSafety": {
    "smokeAlarmsAmount": 3,
    "hasKitchenFireDoors": "Yes",
    "hasFireBlankets": "Yes",
    "hasFireExtinguishers": "Yes",
    "fireExtinguishersInfo": "Fire extinguishers in all rooms.",
    "hasFireDetectionSystem": "Yes",
    "hasSafetyInformation": "Yes",
    "hasRegulationsCompliance": "Yes",
    "hasGasSupply": "Yes",
    "gasSafety": "Yes",
    "fireDoors": "Yes - some",
    "fireDoorsDetails": "Yes",
    "basementOrCellar": "Yes",
    "basementOrCellarDetails": "Yes",
    "fireDetection": "Yes",
    "fireDetectionDetails": "Mains fire system.",
    "emergencyLighting": "Yes",
    "extinguisher": "Yes",
    "fireSafety": "Yes",
    "electricalInstallation": "Yes",
    "gasInstallation": "Yes",
    "electricalSupply": "Yes",
    "exitDoors": "Yes"
  },
  "propertyDetails": {
    "propertyUsage": "House in multiple occupation",
    "propertyStoriesAmount": 2,
    "floorsSituation": "1st and 2nd",
    "buildingStoriesAmount": 7,
    "propertyHouseholdAmount": 2,
    "propertyPeopleAmount": 4,
    "propertyPeopleAmountToLet": 4,
    "propertyHouseholdAmountToLet": 2,
    "occupiedDate": "2021-12-29T14:44:53.658Z",
    "separateLettingsAmount": 2,
    "habitableRoomsAmount": 4,
    "propertyApproxYear": "Post 1991",
    "externalStructures": "Yes",
    "maxOccupants": 8,
    "maxHouseholds": 3,
    "hasBuildingBeenConvertedIntoFlats": "Part of the building",
    "dateOfConversion": "03/1999",
    "howIsTheBuildingOccupied": "Mixed (residential & commercial)",
    "howIsTheBuildingOccupiedInfo": "0 and 1",
    "residentialFlatsNumber": 80,
    "unitsUnderLicenceHolder": 3,
    "residingLicenceHolderInUnit": "Yes",
    "residingLicenceHolderInUnitInfo": "Flat 56"
  },
  "interestedParties": {
    "licenceHolder": "Jonny Smith",
    "personWhoCollectRent": "Jonny Smith",
    "applicant": "Jonny Smith",
    "parties": [
      {
        "title": "Mr",
        "firstName": "Jonny",
        "surname": "Smith",
        "dateOfBirth": "1984-11-25T00:00:00+00:00",
        "companyName": "Jonny's Lets",
        "address": {
          "addressLine1": "76 Joules Court",
          "addressLine2": "Shenley Lodge",
          "addressLine3": "Example Estate",
          "addressLine4": "Abstract City",
          "city": "London",
          "country": "United Kingdom",
          "county": "Sussex",
          "postcode": "A1 2BC",
          "uprn": "12345678910",
          "usrn": "1234567",
          "latitude": "1.230045",
          "longitude": "-5.430021",
          "ward": "Dream Ward"
        },
        "phoneNumber": "07232876394",
        "emailAddress": "jonny.smith6381@gmail.com",
        "partyType": "Other",
        "partyTypeName": "Freeholder - Extended",
        "organisation": true,
        "dateContacted": "2021-12-29T16:36:44+00:00"
      }
    ]
  },
  "dateDraftIssued": "2021-10-28T00:00:00+00:00",
  "dateFinalIssued": "2021-11-18T00:00:00+00:00",
  "dateValidFrom": "2021-11-18T00:00:00+00:00",
  "dateValidTo": "2026-11-17T00:00:00+00:00",
  "totalMaxPersons": 8,
  "totalMaxHouseholds": 3
}

Attributes

referenceNumber string

Unique identifier for the object.

address object

All address data.

address.addressLine1 string

First line of the property's address.

address.addressLine2 string

Second line of the property's address.

address.addressLine3 string

Third line of the property's address.

address.addressLine4 string

Fourth line of the property's address.

address.city string

City of the address.

address.country string

Country of the address.

address.county string

County of the address.

address.postcode string

Postcode of the address.

address.uprn string

Unique Property Reference Number (UPRN) of the address.

address.usrn string

Unique Street Reference Number (USRN) of the address.

address.latitude string

Latitude of the address in decimal degrees (ISO 6709).

address.longitude string

Longitude of the address in decimal degrees (ISO 6709).

address.ward string

Ward of the address.

licencePhase string

Processing phase of this application/licence. Options are Pre-application, Application, Licence, and Exemption.

licenceType object

Set of key-value pairs comprising an identifier and a licence type.

licenceType.id integer

Licence type key-value pair ID.

licenceType.NAME string

Licence type of this application/licence. Options are Mandatory HMO Licence, Additional HMO licence, Selective licence, 257 HMO and Temporary Exemption.

licenceStatus object

Set of key-value pairs comprising an identifier and a licence status.

licenceStatus.id integer

Licence status key-value pair ID.

licenceStatus.NAME string

Licence status of this application/licence.

assignee object

Set of key-value pairs comprising an identifier and an assignee name.

assignee.id integer

Assignee key-value pair ID.

assignee.NAME string

Name of the person currently assigned to this licence/application.

dateSubmitted dateTime

Date and time that the application was submitted by the applicant. ISO 8601 is used e.g. 2021-11-18T14:15:32+00:00.

datePaid dateTime

Date and time that the application was paid for by the applicant. ISO 8601 is used e.g. 2021-11-18T14:15:32+00:00. Note that is split payments is activated, this is the date and time that Fee A was paid.

propertyRooms object

Room data for all rooms in the property.

propertyRooms.bathrooms array of objects

Bathroom data. Separate object for each bathroom.

propertyRooms.bathrooms.location string

Location of the bathroom within the property.

propertyRooms.bathrooms.exclusivity string

Describes whether the bathroom is shared or exclusive. Enum with two values: Shared and Exclusive.

propertyRooms.bathrooms.washHandBasins integer

Number of wash hand basins (sinks) in the bathroom.

propertyRooms.bathrooms.toilets integer

Number of toilets in the bathroom.

propertyRooms.bathrooms.bathsAndShowers integer

Number of baths and/or showers in the bathroom.

propertyRooms.bedrooms array of objects

Bedroom data. Separate object for each bedroom.

propertyRooms.bedrooms.location string

Location of the bedroom within the property.

propertyRooms.bedrooms.size number

Size of the bedroom in m2.

propertyRooms.bedrooms.exclusivity string

Describes whether the bedroom is shared or exclusive. Enum with two values: Shared and Exclusive.

propertyRooms.bedrooms.bathroomFacilities string

Describes whether the bedroom has any bathroom facilities. Enum with two values: Yes and No.

propertyRooms.bedrooms.washBasins integer

Number of wash hand basins (sinks) in the bedroom.

propertyRooms.bedrooms.toilets integer

Number of toilets in the bedroom.

propertyRooms.bedrooms.bathShower integer

Number of baths and/or showers in the bedroom.

propertyRooms.bedrooms.kitchenFacilities string

Describes whether the bedroom has any kitchen facilities. Enum with two values: Yes and No.

propertyRooms.bedrooms.ovens integer

Number of ovens in the bedroom.

propertyRooms.bedrooms.hobs integer

Number of hobs in the bedroom.

propertyRooms.bedrooms.sinks integer

Number of sinks in the bedroom.

propertyRooms.bedrooms.fridges integer

Number of fridges in the bedroom.

propertyRooms.bedrooms.freezers integer

Number of freezers in the bedroom.

propertyRooms.communalRooms array of objects

Communal room data. Separate object for each communal room.

propertyRooms.communalRooms.location string

Communal room location within the property.

propertyRooms.communalRooms.size number

Size of the communal room in m2.

propertyRooms.communalRooms.exclusivity string

Describes whether the communal room is shared or exclusive. Enum with two values: Shared and Exclusive.

propertyRooms.communalRooms.smokeAlarm string

Describes whether the communal room has a smoke alarm. Enum with two values: Yes and No.

propertyRooms.communalRooms.bestDescription string

Details the communal room type. Enum with three values: Dining room, Living room, and Other communal space.

propertyRooms.communalRooms.washHandBasins string

Number of wash hand basins (sinks) in the communal room.

propertyRooms.kitchens array of objects

Kitchen data. Separate object for each kitchen.

propertyRooms.kitchens.location string

Location of the kitchen within the property.

propertyRooms.kitchens.size number

Size of the kitchen in m2.

propertyRooms.kitchens.exclusivity string

Describes whether the kitchen is shared or exclusive. Enum with two values: Shared and Exclusive.

propertyRooms.kitchens.smokeAlarm string

Describes whether the kitchen has a smoke alarm. Enum with two values: Yes and No.

propertyRooms.kitchens.ovens integer

Number of ovens in the kitchen.

propertyRooms.kitchens.hobs integer

Number of hobs in the kitchen.

propertyRooms.kitchens.sinks integer

Number of sinks in the kitchen.

propertyRooms.kitchens.fridges integer

Number of fridges in the kitchen.

propertyRooms.kitchens.freezers integer

Number of freezers in the kitchen.

propertyUnits object

Unit data for all units in the property. This is only applicable for section 257 property types.

propertyUnits.unitsNotUnderLicenceHolder array of objects

Unit data for units that are not under licence holder's control. Separate object for each unit.

propertyUnits.unitsNotUnderLicenceHolder.name string

Name/number of the unit within the property.

propertyUnits.unitsNotUnderLicenceHolder.floor integer

Floor that the unit is on within the property.

propertyUnits.unitsNotUnderLicenceHolder.occupied string

Describes how the unit is occupied. Enum with four values: Owner occupied, Privately rented, Vacant and Don't know.

propertyUnits.flatsUnderLicenceHolder array of objects

Unit data for units that are under licence holder's control. Separate object for each unit.

propertyUnits.flatsUnderLicenceHolder.name string

Name/number of the unit within the property.

propertyUnits.flatsUnderLicenceHolder.floor integer

Floor that the unit is on within the property.

propertyUnits.flatsUnderLicenceHolder.entrance string

Describes whether the entrance or staircase to the unit is shared with other units or whether it has its own separate entrance. Enum with two values: Shared and Separate.

propertyUnits.flatsUnderLicenceHolder.roomsInFlat integer

Number of rooms in the unit (excluding kitchens and bathrooms).

propertyUnits.flatsUnderLicenceHolder.tenancyType string

Describes the tenancy type. Enum with five values: Assured shorthold tenancy (AST), Assured tenancy, Excluded tenancy or licence (shared accommodation with landlord), Regulated tenancy and Other.

propertyUnits.flatsUnderLicenceHolder.tenancyTypeOther string

Description of tenancy type if Other is selected for tenancyType.

propertyUnits.flatsUnderLicenceHolder.occupiersCount integer

Number of people currently occupying the unit.

propertyUnits.bedsitsUnderLicenceHolder array of objects

Unit data for bedsits/studios that are under the licence holder's control. Separate object for each unit.

propertyUnits.bedsitsUnderLicenceHolder.name string

Name/number of the bedsit/studio within the property.

propertyUnits.bedsitsUnderLicenceHolder.floor integer

Floor that the bedsit/studio is on within the property.

propertyUnits.bedsitsUnderLicenceHolder.entrance string

Describes whether the entrance or staircase to the unit is shared with other units or whether it has its own separate entrance. Enum with two values: Shared and Separate.

propertyUnits.bedsitsUnderLicenceHolder.size number

Size of the bedsit/studio in m2.

propertyUnits.bedsitsUnderLicenceHolder.tenancyType string

Describes the tenancy type. Enum with five values: Assured shorthold tenancy (AST), Assured tenancy, Excluded tenancy or licence (shared accommodation with landlord), Regulated tenancy and Other.

propertyUnits.bedsitsUnderLicenceHolder.tenancyTypeOther string

Description of tenancy type if Other is selected for tenancyType.

propertyUnits.bedsitsUnderLicenceHolder.occupiersCount integer

Number of people currently occupying the bedsit/studio.

eligibilityInformation object

Eligibility data of all interested parties.

eligibilityInformation.unspentConvictions string

Describes whether any of the interested parties have unspent convictions. Enum with two values: Yes and No.

eligibilityInformation.unspentConvictionsDetails string

Details of any unspent convictions.

eligibilityInformation.unlawfulDiscrimination string

Describes whether any of the interested parties have been involved with any unlawful discrimination. Enum with two values: Yes and No.

eligibilityInformation.unlawfulDiscriminationDetails string

Details of any unlawful discrimination.

eligibilityInformation.judgementMadeAgainstYou string

Describes whether any of the interested parties have had a judgement made against them relating to Housing, Public Health, Environmental Health or Landlord and Tenant Law. Enum with two values: Yes and No.

eligibilityInformation.judgementMadeAgainstYouDetails string

Details of any judgements made against an interested party.

eligibilityInformation.experienceOfManagingRentedProperty string

Describes whether the licence holder or manager has any experience of managing rented property. Enum with two values: Yes and No.

eligibilityInformation.licenceHolderBelongToLandlords string

Describes whether the licence holder is an accredited landlord. Enum with two values: Yes and No.

eligibilityInformation.nameOfAssociation string

Name of the landlord's accreditation association or regulation.

eligibilityInformation.registrationNumber string

Landlord's accreditation registration/certificate number.

eligibilityInformation.propertyVisited string

Describes whether the property is visited to check its condition and for any antisocial activities of the tenants. Enum with two value: Yes and No.

eligibilityInformation.hasFunds string

Describes whether there are funds to deal with uninsured damage/insurance and maintenance to the property. Enum with two values: Yes and No.

eligibilityInformation.fundsInfo string

Details of funding arrangements for dealing with emergency repairs, uninsured damage, necessary maintenance or general upkeep of the property.

eligibilityInformation.hasPropertyInControlToManagementOrder string

Describes whether any of the interested parties have been in control of a property that was subject to a Management Order, in the last five year. Enum with two values: Yes and No.

eligibilityInformation.hasPropertyInControlToManagementOrderDetails string

Names of people who have been in control of a property that was subject to a Management Order.

eligibilityInformation.hasPropertyThatHasBeenRefused string

Describes whether any of the interested parties have been in control of a property that has been refused a licence or breached conditions of a licence, in the last five years. Enum with two values: Yes and No.

eligibilityInformation.hasPropertyThatHasBeenRefusedDetails string

Names of people who have been in control of a property that has been refused a licence or breached conditions of a licence, in the last five years.

eligibilityInformation.regularInspection string

Describes whether the property is regularly inspected for the routine maintenance and management of the common parts. Enum with two values: Yes and No. Only applies to s257 properties.

eligibilityInformation.regularInspectionMonthly integer

Number of weeks between inspections. Only applies to s257 properties.

eligibilityInformation.regularInspectionPerson string

Name of the person who carries out inspections. Only applies to s257 properties.

eligibilityInformation.regularCleaning string

Describes whether there are arrangements in place for the regular cleaning of the common parts of the property. Enum with two values: Yes and No. Only applies to s257 properties.

eligibilityInformation.regularCleaningMonthly integer

Number of weeks between cleaning sessions. Only applies to s257 properties.

eligibilityInformation.regularCleaningPerson string

Name of the person who carries out the cleaning. Only applies to s257 properties.

eligibilityInformation.problems string

Describes if there are any problems of which the council should be made aware. Enum with two values: Yes and No. Only applies to s257 properties.

eligibilityInformation.problemsDetails string

Details of any problems. Only applies to s257 properties.

healthAndSafety object

Property health and safety information for the licence/application.

healthAndSafety.smokeAlarmsAmount integer

Number of smoke alarms in the property.

healthAndSafety.hasKitchenFireDoors string

Describes whether the kitchen has fire doors. Enum with two values: Yes and No.

healthAndSafety.hasFireBlankets string

Describes whether the kitchen has fire blankets. Enum with two values: Yes and No.

healthAndSafety.hasFireExtinguishers string

Describes whether the stairways have fire extinguishers. Enum with three values: Yes, No and Not applicable.

healthAndSafety.fireExtinguishersInfo string

Details as to why fire extingushers in stairways are not applicable.

healthAndSafety.hasFireDetectionSystem string

Describes whether there is a mains powered fire detection system in the property. Enum with two values: Yes and No.

healthAndSafety.hasSafetyInformation string

Describes whether the occupiers are provided with details of escape routes and other fire safety information. Enum with two values: Yes and No.

healthAndSafety.hasRegulationsCompliance string

Describes whether furniture provided within the property complies with Fire Safety Regulations. Enum with three values: Yes, No and Not applicable.

healthAndSafety.hasGasSupply string

Describes whether the property has a gas supply. Enum with two values: Yes and No.

healthAndSafety.gasSafety string

Describes whether all gas appliances in the property meet the health and safety standards of relevant gas safety legislation and are tested annually, for properties with a gas supply. Enum with two values: Yes and No.

healthAndSafety.fireDoors string

Describes whether fire doors are installed in all properties under the licence holder’s control. Enum with three values: Yes - all, Yes - some and No. Only applies to s257 properties.

healthAndSafety.fireDoorsDetails string

Describes whether all other entrance doors to the flats are 30-minute fire doors, with smoke seals and intumescent strips, if fire doors are only installed in some, or none, of the properties under the licence holder's controlled. Enum with three values: Yes, No and Don't know. Only applies to s257 properties.

healthAndSafety.basementOrCellar string

Describes whether any of the properties have a basement or cellar. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.basementOrCellarDetails string

Describes whether the cellar or basement has a fire protected ceiling (plaster board or fire boarding) and a fire door. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.fireDetection string

Describes if the common parts have a fire detection or alarm system installed. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.fireDetectionDetails string

Details of the fire detection or alarm system, if one is installed in the common parts. Only applies to s257 properties.

healthAndSafety.emergencyLighting string

Describes if there is any emergency lighting in the halls and stairways. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.extinguisher string

Describes if there is a fire extingusher in the halls and stairways. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.fireSafety string

Describes whether a fire safety risk assessment been undertaken at the building. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.electricalInstallation string

Describes whether the electrical installation and any fixed electrical appliances have been tested within the last five years. Enum with three values: Yes, No and Not applicable. Only applies to s257 properties.

healthAndSafety.gasInstallation string

Describes whether there are gas or electrical installations (e.g. meters) in the common parts/areas. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.electricalSupply string

Describes whether there is a separate landlord electrical supply for the common parts. Enum with two values: Yes and No. Only applies to s257 properties.

healthAndSafety.exitDoors string

Describes whether the main exit door(s) from the property have secure locks that can be opened from the inside without the use of a key. Enum with two values: Yes and No. Only applies to s257 properties.

propertyDetails object

Detailed information about the property primarily regarding layout and occupation.

propertyDetails.propertyUsage string

Describes how the property is used/occupied. Enum with four values: House in multiple occupation, Flat in multiple occupation, House rented to single household and Flat rented to single household.

propertyDetails.propertyStoriesAmount integer

Number of storeys in the property.

propertyDetails.floorsSituation string

Describes on what floors of the building the property's stories are situated.

propertyDetails.buildingStoriesAmount integer

Number of stories in the entire building.

propertyDetails.propertyHouseholdAmount integer

Number of households that currently live in the property.

propertyDetails.propertyPeopleAmount integer

Number of people that currently live in the property.

propertyDetails.propertyPeopleAmountToLet integer

Proposed number of people that will live in the property if there are no current occupants but it is planned for there to be occupants living in the property in the near future.

propertyDetails.propertyHouseholdAmountToLet integer

Proposed number of households that will live in the property if there are no current occupants but it is planned for there to be occupants living in the property in the near future.

propertyDetails.occupiedDate dateTime

Date that it is intended for there to be tenants occupying the property.

propertyDetails.separateLettingsAmount integer

Number of separate lettings in the property.

propertyDetails.habitableRoomsAmount integer

Number of habitable rooms in the property.

propertyDetails.propertyApproxYear string

Approximate year that the building was constructed. Enum with six values: Pre 1919, 1919 - 1944, 1945 - 1964, 1965 - 1980, 1981 - 1991 and Post 1991.

propertyDetails.externalStructures string

Describes if there are any external structures, outbuildings or sheds used as part of the living accommodation. Enum with two values: Yes and No.

propertyDetails.hasBuildingBeenConvertedIntoFlats string

Describes whether the whole building, or part of the building, has been converted into flats. Enum with two values: Whole building and Part of the building. Only applies to s257 properties.

propertyDetails.dateOfConversion string

Date of the conversion. Only applies to s257 properties.

propertyDetails.howIsTheBuildingOccupied string

Describes how the building is occupied. Enum with two values: Residential and Mixed (residential & commercial). Only applies to s257 properties.

propertyDetails.howIsTheBuildingOccupiedInfo string

Describes what storeys are in commercial use (for mixed occupancy buildings). Only applies to s257 properties.

propertyDetails.residentialFlatsNumber integer

Total number of residential flats in the building. Only applies to s257 properties.

propertyDetails.unitsUnderLicenceHolder integer

Total number of units in the building that are under the control of the licence holder. Only applies to s257 properties.

propertyDetails.residingLicenceHolderInUnit string

Describes if the licence holder is residing in any of the units within the building. Only applies to s257 properties.

propertyDetails.residingLicenceHolderInUnitInfo string

Describes which unit the licence holder resides in, if the licence holder resides in the building. Only applies to s257 properties.

interestedParties object

Details about all of the interested parties associated with the property/licence.

interestedParties.licenceHolder string

Name of the licence holder

interestedParties.personWhoCollectRent string

Name of the person who collects the rent.

interestedParties.applicant string

Name of the applicant / portal account holder (PAH).

interestedParties.parties array of objects

Interested party data. Separate object for each interested party.

interestedParties.parties.title string

Title of the interested party.

interestedParties.parties.firstName string

First name of the interested party.

interestedParties.parties.surname string

Surname of the interested party.

interestedParties.parties.dateOfBirth dateTime

Date of birth of the interested party.

interestedParties.parties.companyName string

Comapny name of the interested party (if it's a company).

interestedParties.parties.address object

All address data of the interested party.

interestedParties.parties.address.addressLine1 string

First line of the property's address.

interestedParties.parties.address.addressLine2 string

Second line of the property's address.

interestedParties.parties.address.addressLine3 string

Third line of the property's address.

interestedParties.parties.address.addressLine4 string

Fourth line of the property's address.

interestedParties.parties.address.city string

City of the address.

interestedParties.parties.address.country string

Country of the address.

interestedParties.parties.address.county string

County of the address.

interestedParties.parties.address.postcode string

Postcode of the address.

interestedParties.parties.address.uprn string

Unique Property Reference Number (UPRN).

interestedParties.parties.address.usrn string

Unique Street Reference Number (USRN).

interestedParties.parties.address.latitude string

Latitude in decimal degrees (ISO 6709).

interestedParties.parties.address.longitude string

Longitude in decimal degrees (ISO 6709).

interestedParties.parties.address.ward string

Ward of the address.

interestedParties.parties.phoneNumber string

Phone number of the interested party.

interestedParties.parties.emailAddress string

Email address of the interested party.

interestedParties.parties.partyType string

Interested party type. Values are: Freeholder, Leaseholder, Managing agent, Mortgage provider and Other.

interestedParties.parties.partyTypeName string

If the interested party type is Other then this is the description of the party type.

interestedParties.parties.organisation boolean

Describes whether the interested party is an organisation (TRUE) or an individual (FALSE).

interestedParties.parties.dateContacted dateTime

Date that the interested party was informed about the licence application.

dateDraftIssued dateTime

Date that the draft licence was issued.

dateFinalIssued dateTime

Date that the final licence was issued.

dateValidFrom dateTime

Date the licence is valid from.

dateValidTo dateTime

Date the licence expires.

totalMaxPersons integer

Total maximum permitted number of persons that can reside in the property.

totalMaxHouseholds integer

Total maximum permitted number of households that can reside in the property.

List all licences

GET /licences

$ curl 'https://your_council.metastreet.co.uk/api/v1.1/licences' \
-H 'x-auth-api-token: 3b07c593c309ebf41330cd6f6867610eb18abe43dcf1d'

EXAMPLE RESPONSE

{
  "object": "licence",
  "url": "/api/v1.1/licences",
  "pageSize": 100,
  "currentPage": 1,
  "totalPages": 5,
  "totalCount": 401,
  "data": [
    {
      "referenceNumber": "YCO-583484913397",
      "address": {
        "addressLine1": "4 Dasher Place",
        "addressLine2": "Dasher Street",
        "addressLine3": "Dasher Estate",
        "addressLine4": "Dasher",
        "city": "London",
        "country": "United Kingdom",
        "postcode": "A1 2BC",
        "uprn": "12345678910",
        "usrn": "1234567",
        "latitude": "1.230045",
        "longitude": "-5.430021",
        "ward": "Dasher Ward"
      },
      "licencePhase": "Application",
      "licenceType": {
        "id": 3,
        "name": "Selective licence"
      },
      "licenceStatus": {
        "id": 12,
        "name": "Checks in progress"
      },
      "assignee": {
        "id": 7,
        "name": "Finn Wood"
      },
      "dateSubmitted": "2021-11-26T09:32:08+00:00",
      "datePaid": "2021-11-26T09:32:08+00:00",
      "propertyRooms": {
        "bathrooms": [
          {
            "location": "First floor rear",
            "exclusivity": "Shared",
            "washHandBasins": 1,
            "toilets": 1,
            "bathsAndShowers": 2
          }
        ],
        "bedrooms": [
          {
            "location": "First floor front",
            "size": 25.0,
            "exclusivity": "Exclusive",
            "bathroomFacilities": "No",
            "washBasins": 0,
            "toilets": 0,
            "bathShower": 0,
            "kitchenFacilities": "No",
            "ovens": 0,
            "hobs": 0,
            "sinks": 0,
            "fridges": 0,
            "freezers": 0
          }
        ],
        "communalRooms": [
          {
            "location": "Ground floor north side",
            "size": 45.0,
            "exclusivity": "Shared",
            "smokeAlarm": "Yes",
            "bestDescription": "Living room",
            "washHandBasins": 0
          }
        ],
        "kitchens": [
          {
            "location": "Ground floor rear",
            "size": 15.45,
            "exclusivity": "Shared",
            "smokeAlarm": "Yes",
            "ovens": 1,
            "hobs": 1,
            "sinks": 1,
            "fridges": 1,
            "freezers": 1
          }
        ]
        ...
      },
      "eligibilityInformation": {
        "unspentConvictions": "No",
        "unlawfulDiscrimination": "No",
        "judgementMadeAgainstYou": "No",
        "experienceOfManagingRentedProperty": "No",
        "licenceHolderBelongToLandlords": "No",
        "propertyVisited": "No",
        "hasFunds": "Yes",
        "hasPropertyInControlToManagementOrder": "No",
        "hasPropertyThatHasBeenRefused": "No"
      },
      "healthAndSafety": {
        "hasKitchenFireDoors": "No",
        "hasFireBlankets": "No",
        "hasFireExtinguishers": "No",
        "hasFireDetectionSystem": "Yes",
        "hasSafetyInformation": "Yes",
        "hasRegulationsCompliance": "Yes",
        "hasGasSupply": "No"
      },
      "propertyDetails": {
        "propertyUsage": "House in multiple occupation",
        "propertyStoriesAmount": 2,
        "floorsSituation": "Ground and first",
        "buildingStoriesAmount": 4,
        "propertyHouseholdAmount": 1,
        "propertyPeopleAmount": 4,
        "separateLettingsAmount": 1,
        "habitableRoomsAmount": 3,
        "propertyApproxYear": "Pre 1919",
        "externalStructures": "No"
      },
      "interestedParties": {
        "licenceHolder": "Jonny Smith",
        "personWhoCollectRent": "Jonny Smith",
        "applicant": "Jonny Smith",
        "parties": [
          {
            "title": "Mr",
            "firstName": "Jonny",
            "surname": "Smith",
            "companyName": "ESG Residential",
            "address": {
              "addressLine1": "1 Haberdasher Place",
              "addressLine2": "Church Lane",
              "city": "London",
              "country": "United Kingdom",
              "postcode": "N1 6BS"
            },
            "phoneNumber": "07399374613",
            "emailAddress": "jonny.smith6381@gmail.com",
            "partyType": "Freeholder",
            "organisation": true
          }
          ...
        ]
      },
      ...
      "dateDraftIssued": "2021-10-28T00:00:00+00:00",
      "dateFinalIssued": "2021-11-18T00:00:00+00:00",
      "dateValidFrom": "2021-11-18T00:00:00+00:00",
      "dateValidTo": "2026-11-17T00:00:00+00:00",
      "totalMaxPersons": 6,
      "totalMaxHouseholds": 2
    },
    ...
  ]
}
Returns a list of your licences. The licences are returned sorted by uprn, with the properties with the lowest uprn appearing first.

Parameters

postcode optional

A filter on the list based on the licence’s postcode field. The value must be a string. The filter is not case-sensitive and spaces can removed.

uprn optional

A filter on the list based on the licence’s uprn field. The value must be a string.

licenceTypeId optional

A filter on the list based on the licence’s licenceTypeId field. The value must be an integer.

licenceStatusId optional

A filter on the list based on the licence’s licenceStatusId field. The value must be an integer.

assigneeId optional

A filter on the list based on the licence’s assigneeId field. The value must be an integer.

Pagination parameters are also available - see Pagination.

Returns

A dictionary with a data property that contains an array of licences. Each entry in the array is a separate licence object. If no more licences are available, the resulting array will be empty. This request should never return an error.

Retrieve a licence

GET /licences/:referenceNo

$ curl 'https://your_council.metastreet.co.uk/api/v1.1/licences/YCO-58348491339' \
-H 'x-auth-api-token: 3b07c593c309ebf41330cd6f6867610eb18abe43dcf1d'

EXAMPLE RESPONSE

{
  "object": "licence",
  "url": "/api/v1.1/licences",
  "pageSize": 100,
  "currentPage": 1,
  "totalPages": 5,
  "totalCount": 401,
  "data": [
    {
      "referenceNumber": "YCO-583484913397",
      "address": {
        "addressLine1": "4 Dasher Place",
        "addressLine2": "Dasher Street",
        "addressLine3": "Dasher Estate",
        "addressLine4": "Dasher",
        "city": "London",
        "country": "United Kingdom",
        "postcode": "A1 2BC",
        "uprn": "12345678910",
        "usrn": "1234567",
        "latitude": "1.230045",
        "longitude": "-5.430021",
        "ward": "Dasher Ward"
      },
      "licencePhase": "Application",
      "licenceType": {
        "id": 3,
        "name": "Selective licence"
      },
      "licenceStatus": {
        "id": 12,
        "name": "Checks in progress"
      },
      "assignee": {
        "id": 7,
        "name": "Finn Wood"
      },
      "dateSubmitted": "2021-11-26T09:32:08+00:00",
      "datePaid": "2021-11-26T09:32:08+00:00",
      "propertyRooms": {
        "bathrooms": [
          {
            "location": "First floor rear",
            "exclusivity": "Shared",
            "washHandBasins": 1,
            "toilets": 1,
            "bathsAndShowers": 2
          }
        ],
        "bedrooms": [
          {
            "location": "First floor front",
            "size": 25.0,
            "exclusivity": "Exclusive",
            "bathroomFacilities": "No",
            "washBasins": 0,
            "toilets": 0,
            "bathShower": 0,
            "kitchenFacilities": "No",
            "ovens": 0,
            "hobs": 0,
            "sinks": 0,
            "fridges": 0,
            "freezers": 0
          }
        ],
        "communalRooms": [
          {
            "location": "Ground floor north side",
            "size": 45.0,
            "exclusivity": "Shared",
            "smokeAlarm": "Yes",
            "bestDescription": "Living room",
            "washHandBasins": 0
          }
        ],
        "kitchens": [
          {
            "location": "Ground floor rear",
            "size": 15.45,
            "exclusivity": "Shared",
            "smokeAlarm": "Yes",
            "ovens": 1,
            "hobs": 1,
            "sinks": 1,
            "fridges": 1,
            "freezers": 1
          }
        ]
        ...
      },
      "eligibilityInformation": {
        "unspentConvictions": "No",
        "unlawfulDiscrimination": "No",
        "judgementMadeAgainstYou": "No",
        "experienceOfManagingRentedProperty": "No",
        "licenceHolderBelongToLandlords": "No",
        "propertyVisited": "No",
        "hasFunds": "Yes",
        "hasPropertyInControlToManagementOrder": "No",
        "hasPropertyThatHasBeenRefused": "No"
      },
      "healthAndSafety": {
        "hasKitchenFireDoors": "No",
        "hasFireBlankets": "No",
        "hasFireExtinguishers": "No",
        "hasFireDetectionSystem": "Yes",
        "hasSafetyInformation": "Yes",
        "hasRegulationsCompliance": "Yes",
        "hasGasSupply": "No"
      },
      "propertyDetails": {
        "propertyUsage": "House in multiple occupation",
        "propertyStoriesAmount": 2,
        "floorsSituation": "Ground and first",
        "buildingStoriesAmount": 4,
        "propertyHouseholdAmount": 1,
        "propertyPeopleAmount": 4,
        "separateLettingsAmount": 1,
        "habitableRoomsAmount": 3,
        "propertyApproxYear": "Pre 1919",
        "externalStructures": "No"
      },
      "interestedParties": {
        "licenceHolder": "Jonny Smith",
        "personWhoCollectRent": "Jonny Smith",
        "applicant": "Jonny Smith",
        "parties": [
          {
            "title": "Mr",
            "firstName": "Jonny",
            "surname": "Smith",
            "companyName": "ESG Residential",
            "address": {
              "addressLine1": "1 Haberdasher Place",
              "addressLine2": "Church Lane",
              "city": "London",
              "country": "United Kingdom",
              "postcode": "N1 6BS"
            },
            "phoneNumber": "07399374613",
            "emailAddress": "jonny.smith6381@gmail.com",
            "partyType": "Freeholder",
            "organisation": true
          }
          ...
        ]
      },
      ...
      "dateDraftIssued": "2021-10-28T00:00:00+00:00",
      "dateFinalIssued": "2021-11-18T00:00:00+00:00",
      "dateValidFrom": "2021-11-18T00:00:00+00:00",
      "dateValidTo": "2026-11-17T00:00:00+00:00",
      "totalMaxPersons": 6,
      "totalMaxHouseholds": 2
    },
    ...
  ]
}
Retrieves a Licence object.

Parameters

No parameters.

Returns

Returns the Licence object for a valid identifier.