# Inventory API

The Inventory API is divided in two groups, Bulk API endpoints and REST API endpoints. The first ones are intended to import all the inventory in a single request, very similar to the use of CSV files, while the second ones are intended to keep an external system synchronized with KPro Marketing.

You need to pass the QueryString parameter api_key with your API key to all the API requests.

Bulk API
- Developments and their properties
- Independent units
REST API
Additional information
- Label conventions
- Understanding prices fields

# Bulk API

The Bulk API endpoints can be used to import developments and their properties, but also to import independent units. The importation process will insert non-existent items, and will update the ones that were already loaded into KPro Marketing.

Warning

Bulk API endpoints will not delete or archive existing items that are not coming in the payload.

It also provides one endpoint to get all the developments with their properties in a single payload, and another to get all the independent units.

Info

In KPro Marketing developments and independent units can have three different visibility status: visible, hidden and archived. When using the Bulk API only visible elements are returned.

# Developments and their properties

When using bulk operations, a single request is used to update all the developments and their properties, sending the whole inventory in the payload. This is very useful to transfer all new-home properties from a previous system to KPro Marketing.

# Get the list of all developments and properties

To get a JSON with all developments and their properties send a GET to /api/bulk/open/developments.

The response will be a non-paginated collection of developments, where each item will contain a collection of properties. This response can be used as a backup of all your new-home properties.

{
  "data": [
    {
      "name": "Park Apartments",
      "developerName": "Story Homes",
      "warrantyProvider": "Peacock insurance",
      "warrantyNumber": "abc-123",
      "constructionType": "Pre-cast concrete",
      "building": "Lincoln House",
      "street": "Eltham Green",
      "postcode": "SE3 9SD",
      "town": "Eltham",
      "externalReference": "DEV-12345",
      "localAuthority": "Greenwich",
      "properties": [
        {
          "propertyNumber": "12",
          "externalReference": "PROP-67890",
          "schemeGroup": "shared-ownership",
          "availabilityStatus": "available",
          "propertyType": "semi-detached-house",
          "active": true,
          "forSale": true,
          "useDevelopmentAddress": true,
          "building": null,
          "street": null,
          "town": null,
          "postcode": null,
          "localAuthority": null,
          "handoverDate": "2020-10-12",
          "bedrooms": 3,
          "bathrooms": 1,
          "receptionRooms": 1,
          "floorArea": 72,
          "numberOfFloors": 2,
          "floor": "ground",
          "liftProvided": false,
          "furnitureStatus": "furnished",
          "tenure": "leasehold",
          "leaseYears": 125,
          "features": ["driveway", "private-garden"],
          "keyFeatures": ["Great location", "Excellent Transport Links", "Lots to do nearby"],
          "floorplanImages": [
            {
              "url": "https://static.keaze.co.uk/assets/plots/5646/images/floor-plan.png",
              "source": "https://yourserver.com/images/4534/floor-plan.png",
              "caption": null,
              "alt": "floor plan"
            }
          ],
          "energyEfficiencyRatingCurrent": 83,
          "environmentalImpactRatingCurrent": 86,
          "autoGenerateKid": false,
          "freeholdTransferOption": 1,
          "transferOfFreeholdReason": null,
          "kid": [
            {
              "url": "https://static.keaze.co.uk/assets/plots/5646/kids/sample.pdf",
              "source": "https://yourserver.com/pdfs/4534/sample.pdf",
              "caption": "Important document"
            }
          ],
          "fullMarketPrice": 205000,
          "depositPercentage": 5,
          "minSharePercentage": 45,
          "maxSharePercentage": 75,
          "subsidisedRent": 2.75,
          "subsidisedAsYearlyPercent": true,
          "monthlyServiceCharge": 43,
          "annualGroundRent": null,
          "reservationFee": null,
          "administrationFee": null,
          "estateCharge": 30,
          "buildingsInsurance": 15,
          "managementFee": 20,
          "reserveFundPayment": null,
          "wardenServicesPayment": null,
          "otherMonthlyCosts": null,
          "monthlyRent": null,
          "rentalDeposit": null,
          "minTenancyMonths": null,
          "maxTenancyMonths": null,
          "fullSpecification": "<p>Modern 3-bedroom house with kitchen and dining area, fully fitted kitchen, high level double oven, hob and hood, sitting room, en suite and fitted wardrobe to the Master bedroom and parking</p>"
        },
        {...},
        {...}
      ]
    },
    {...},
    {...}
  ]
}

Development fields

Field name	Type	Nullable	Description
`name`	string	No	Name for the development. It should be unique among all the developments.
`developerName`	string	Yes	Developer name
`warrantyProvider`	string	Yes	Warranty provider
`warrantyNumber`	string	Yes	Warranty number
`constructionType`	string	Yes	Construction type
`building`	string	Yes	Name or number for the building.
`street`	string	Yes	The name of the road on which the development is principally adjacent.
`postcode`	string	No	The development postal area code.
`town`	string	Yes	The nearest large urban area to the development.
`externalReference`	string	Yes	Reference for users to identify the development in their system.
`localAuthority`	string	No	The local authority name where the development is.
`properties`	array	Yes	The collection of properties.

Property fields

Field name	Type	Nullable	Description
`propertyNumber`	string	No	Alphanumeric value that identifies the property in the development. It should be unique in the scope of its development.
`externalReference`	string	Yes	Reference for users to identify the property in their system.
`schemeGroup`	string	No	Scheme groups under the property is sold or rented.
`availabilityStatus`	string	No	One of the four possible availability status, regardless the property is for sale or to rent.
`propertyType`	string	No	Describe the type of property.
`active`	boolean	No	Whether the property is active or not.
`forSale`	boolean	No	Whether the property is for sale (true) or to rent (false).
`useDevelopmentAddress`	boolean	No	Whether the address come from development. If false, the next 5 fields will be null.
`building`	string	Yes	The building name or number where the property belongs.
`street`	string	Yes	The name of the road on which the property is principally adjacent.
`town`	string	Yes	The nearest large urban area to the property.
`postcode`	string	Yes	The property postal area code.
`localAuthority`	string	Yes	The local authority name where the property is.
`handoverDate`	string	Yes	Property handover date.
`bedrooms`	number	No	The total number of bedrooms within the property.
`bathrooms`	number	No	The number of bathrooms within the property.
`receptionRooms`	number	No	The number of reception rooms within the property.
`floorArea`	number	Yes	Area occupied by the property floor in square meters.
`numberOfFloors`	number	No	How many floors the property occupies or consists of. Usually 1, but most of detached and semi-detached houses consist of 2 floors.
`floor`	string	No	The property entrance floor. Please see the floor labels.
`liftProvided`	boolean	Yes	Lift provided
`furnitureStatus`	string	No	Whether the property is furnished, part-furnished or unfurnished. See the furniture status labels.
`tenure`	string	No	leasehold or freehold
`leaseYears`	number	Yes	When tenure is leasehold, the number of years to use the home from the freeholder.
`features`	array	No	Collection of predefined property features. See the available property feature labels.
`keyFeatures`	array	Yes	Array of free text key features.
`floorplanImages`	array	No	Collection of floorplan images. Every item has 4 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the image was uploaded from if it was added via API. `alt` is the alternative text for the html image and `caption` is an optional caption you would like to display in some portals.
`energyEfficiencyRatingCurrent`	number	Yes	Predicted energy efficiency rating.
`environmentalImpactRatingCurrent`	number	Yes	Predicted environmental impact rating.
`kid`	array	No	Collection of key important documents. Every item has 3 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the file was uploaded from if it was added via API. `caption` is an optional caption you would like to display in some portals.
`fullMarketPrice`	number	Yes	The property full market price when it is for sale.
`depositPercentage`	number	Yes	Percent to compute the lender deposit requirements when the property is for sale.
`minSharePercentage`	number	Yes	Minimum share to buy in percentage when the scheme is shared ownership (between 10 and 100).
`maxSharePercentage`	number	Yes	Maximum share to buy in percentage when the scheme is shared ownership (less or equal than 100).
`subsidisedRent`	number	Yes	It will depend on the subsidisedAsYearlyPercent value. If true the subsidised rent as a yearly percent, otherwise the monthly rent.
`subsidisedAsYearlyPercent`	boolean	No	For shared ownership properties, true is the subsidised value is expressed as a percent of the part the buyer is not going to purchase, false if the subsidised value is a fixed monthly value.
`monthlyServiceCharge`	number	Yes	When the property is for sale, the monthly bill that covers the costs of any repairs or maintenance to the structure of your building, including drainage, insurance and management charges.
`annualGroundRent`	number	Yes	The annual ground rent, made by a holder of a leasehold property to the freeholder or a superior leaseholder, as required under a lease.
`reservationFee`	number	Yes	Fee a buyer may have to pay to reserve a property for a specific period. It is not refundable, but it will usually be deducted from the purchase price if you then go on to complete the purchase of the property.
`administrationFee`	number	Yes	Fee charged by an agency to cover expenses related to record-keeping and/or other administrative costs.
`monthlyRent`	number	Yes	When the property is to rent, the monthly rent payment amount.
`rentalDeposit`	number	Yes	Security deposit to rent the property.
`minTenancyMonths`	number	Yes	Minimum tenancy term in months.
`maxTenancyMonths`	number	Yes	Maximum tenancy term in months.
`fullSpecification`	string	Yes	Details about the property that potential buyers would find useful.
`autoGenerateKid`	boolean	No	Only for Shared Ownership: The Key Information Document will be automatically generated using property information.
`sharedOwnershipType`	object	Yes	The shared ownership type when applicable. It's a {id, name} object from the list in Shared ownership types.
`estateCharge`	number	Yes	Fee to maintain the grounds and includes services such as gardening, litter picking and general grounds maintenance.
`buildingsInsurance`	number	Yes	Buildings insurance covers the cost of repairing damage to the structure of your property. Garages, sheds and fences are also covered, as well as the cost of replacing items such as pipes, cables and drains.
`managementFee`	number	Yes	Fee payable to the Manager for its day-to-day management of the Property pursuant to the Management Agreement.
`reserveFundPayment`	number	Yes	Fund set aside to cover the cost of major works or other significant items of expenditure expected in the foreseeable future, usually a period of 10-20 years.
`wardenServicesPayment`	number	Yes	Warden services/person centred services payment.
`otherMonthlyCosts`	number	Yes	Other monthly costs (e.g. alarm)
`freeholdTransferOption`	number	Yes	Only for Shared Ownership: Transfer of freehold statement. Please see the freehold transfer options.
`transferOfFreeholdReason`	string	Yes	Only for Shared Ownership: Transfer of freehold non-transfer reason, depending on the option.
`wardenServiceDetails`	string	Yes	Copy for section warden services/person centred services to generate kid documents.
`petsExtraInfo`	string	Yes	Additional information about pets, useful for kid generation.

# Importing developments and properties

To import all the developments and their properties issue a POST to /api/bulk/open/developments.

The payload must be similar to the JSON response when requesting the list of all developments and properties. A JSON object with the field data containing all the collection of developments with their properties. The fields structure for developments and properties should match the one detailed above, except some fields that are not necessary because they are computed fields:

development.localAuthority
property.forSale
property.localAuthority

In the case of floorplan images, the field url is not necessary, and only the field source is mandatory from the other three fields.

Nullable fields can be omitted, but in those cases null values will be used when updating the development or property. Although price fields are all nullables, it is because they depend on the occupancy type and the scheme group, and they could be required depending on these values. Check the section Understanding price fields.

The payload is validated before importing, and if any of the field value is invalid the whole action is cancelled and no development or property is updated or inserted. In those cases a message with all the errors is returned.

Example

{
  "data": [
    {
      "name": "Park Apartments",
      "developerName": "Story Homes",
      "warrantyProvider": "Peacock insurance",
      "warrantyNumber": "abc-123",
      "constructionType": "Pre-cast concrete",
      "building": "Lincoln House",
      "street": "Eltham Green",
      "postcode": "SE3 9SD",
      "town": "Eltham",
      "externalReference": "DEV-12345",
      "properties": [
        {
          "propertyNumber": "12",
          "externalReference": "PROP-67890",
          "schemeGroup": "shared-ownership",
          "availabilityStatus": "available",
          "propertyType": "semi-detached-house",
          "active": true,
          "useDevelopmentAddress": true,
          "building": null,
          "street": null,
          "town": null,
          "postcode": null,
          "handoverDate": "2020-10-12",
          "bedrooms": 3,
          "bathrooms": 1,
          "receptionRooms": 1,
          "floorArea": 72,
          "numberOfFloors": 2,
          "floor": "ground",
          "liftProvided": false,
          "furnitureStatus": "furnished",
          "tenure": "leasehold",
          "leaseYears": 125,
          "features": ["driveway", "private-garden"],
          "keyFeatures": ["Great location", "Excellent Transport Links", "Lots to do nearby"],
          "floorplanImages": [
            {
              "source": "https://yourserver.com/images/4534/floor-plan.png",
              "caption": null,
              "alt": "floor plan"
            }
          ],
          "energyEfficiencyRatingCurrent": 83,
          "environmentalImpactRatingCurrent": 86,
          "autoGenerateKid": false,
          "freeholdTransferOption": 1,
          "transferOfFreeholdReason": null, 
          "kid": [
            {
              "url": "https://yourserver.com/pdfs/4534/sample.pdf",
              "caption": "Important document"
            }
          ],
          "fullMarketPrice": 205000,
          "depositPercentage": 5,
          "minSharePercentage": 45,
          "maxSharePercentage": 75,
          "subsidisedRent": 2.75,
          "subsidisedAsYearlyPercent": true,
          "monthlyServiceCharge": 43,
          "annualGroundRent": null,
          "reservationFee": null,
          "administrationFee": null,
          "estateCharge": 30,
          "buildingsInsurance": 15,
          "managementFee": 20,
          "reserveFundPayment": null,
          "wardenServicesPayment": null,
          "otherMonthlyCosts": null,
          "monthlyRent": null,
          "rentalDeposit": null,
          "minTenancyMonths": null,
          "maxTenancyMonths": null,
          "fullSpecification": "<p>Modern 3-bedroom house with kitchen and dining area, fully fitted kitchen, high level double oven, hob and hood, sitting room, en suite and fitted wardrobe to the Master bedroom and parking</p>"
        },
        {...},
        {...}
      ]
    },
    {...},
    {...}
  ]
}

# Independent units

Independent units are properties that doesn't belong to any development. They can be resale properties or just new-build properties that are going to be advertised independently.

They share the same fields structure as development properties, except some minor differences:

They use field name instead propertyNumber
They always require address fields: building, street, town and postcode
They require field newBuild to specify if it's a new-build property or not
Besides current energy efficiency rating and current environmental impact rating, potential values can be specified for resale properties.

# Get the list of all independent units

To get a JSON with all the independent units issue a GET to /api/bulk/open/independent-units.

The response will be a non-paginated collection of properties, where object fields are very similar to the ones used for development properties, except for the differences explained above.

{
  "data": [
    {
      "name": "Old Farm Place",
      "externalReference": "PROP-67890",
      "schemeGroup": "shared-ownership",
      "availabilityStatus": "available",
      "propertyType": "flat",
      "newBuild": false,
      "active": true,
      "forSale": true,
      "building": "",
      "street": "Old Farm Avenue",
      "town": "Sidcup",
      "postcode": "DA15 8AW",
      "localAuthority": "Bexley",
      "handoverDate": "2018-01-23",
      "bedrooms": 2,
      "bathrooms": 1,
      "receptionRooms": 1,
      "floorArea": 64,
      "numberOfFloors": 1,
      "floor": "ground",
      "liftProvided": false,
      "furnitureStatus": "furnished",
      "tenure": "leasehold",
      "leaseYears": 125,
      "leaseStartDate": "2021-01-25",
      "features": ["off-street-parking", "communal-garden", "wheelchair-accessible"],
      "keyFeatures": ["Great location", "Excellent Transport Links", "Lots to do nearby"],
      "floorplanImages": [
        {
          "url": "https://static.keaze.co.uk/assets/properties/4576/images/floor-plan.png",
          "source": "https://yourserver.com/images/6575/floor-plan.png",
          "caption": null,
          "alt": "floor plan"
        }
      ],
      "energyEfficiencyRatingCurrent": 82,
      "energyEfficiencyRatingPotential": 90,
      "environmentalImpactRatingCurrent": 86,
      "environmentalImpactRatingPotential": 92,
      "autoGenerateKid": false,
      "freeholdTransferOption": 1,
      "transferOfFreeholdReason": null, 
      "kid": [
        {
          "url": "https://yourserver.com/pdfs/4534/sample.pdf",
          "caption": "Important document"
        }
      ],
      "fullMarketPrice": 230000,
      "depositPercentage": 5,
      "minSharePercentage": 45,
      "maxSharePercentage": 75,
      "subsidisedRent": 431.25,
      "subsidisedAsYearlyPercent": false,
      "monthlyServiceCharge": 108.9,
      "annualGroundRent": null,
      "reservationFee": null,
      "administrationFee": null,
      "estateCharge": 30,
      "buildingsInsurance": 15,
      "managementFee": 20,
      "reserveFundPayment": null,
      "wardenServicesPayment": null,
      "otherMonthlyCosts": null,
      "monthlyRent": null,
      "rentalDeposit": null,
      "minTenancyMonths": null,
      "maxTenancyMonths": null,
      "fullSpecification": "<p><strong>GENERAL</strong></p><ul><li>Open plan layout</li><li>Cool and contemporary interior</li><li>Ample storage throughout</li><li>Welcoming and modern communal areas</li><li>Bold outdoor spaces</li></ul><p><strong>KITCHEN</strong></p><ul><li>Ample workspaces</li><li>Fridge/freezer</li><li>Washer/dryer</li><li>Dishwasher</li><li>Separate electric oven and gas hob plus extractor fans</li></ul>"
    },
    {...},
    {...}
  ]
}

Fields

Field name	Type	Nullable	Description
`name`	string	No	Name for the independent unit. It should be unique among all the independent units.
`externalReference`	string	Yes	Reference for users to identify the property in their system.
`schemeGroup`	string	No	Scheme groups under the property is sold or rented.
`availabilityStatus`	string	No	One of the four possible availability status, regardless the property is for sale or to rent.
`propertyType`	string	No	Describe the type of property.
`newBuild`	boolean	No	Whether the property is new build or not.
`active`	boolean	No	Whether the property is active or not.
`forSale`	boolean	No	Whether the property is for sale (true) or to rent (false).
`building`	string	Yes	The building name or number where the property belongs.
`street`	string	Yes	The name of the road on which the property is principally adjacent.
`town`	string	Yes	The nearest large urban area to the property.
`postcode`	string	No	The property postal area code.
`localAuthority`	string	No	The local authority name where the property is.
`handoverDate`	string	Yes	Property handover date.
`bedrooms`	number	No	The total number of bedrooms within the property.
`bathrooms`	number	No	The number of bathrooms within the property.
`receptionRooms`	number	No	The number of reception rooms within the property.
`floorArea`	number	Yes	Area occupied by the property floor in square meters.
`numberOfFloors`	number	No	How many floors the property occupies or consists of. Usually 1, but most of detached and semi-detached houses consist of 2 floors.
`floor`	string	No	The property entrance floor. Please see the floor labels.
`liftProvided`	boolean	Yes	Lift provided
`furnitureStatus`	string	No	Whether the property is furnished, part-furnished or unfurnished. See the furniture status labels.
`tenure`	string	No	leasehold or freehold
`leaseYears`	number	Yes	When tenure is leasehold, the number of years to use the home from the freeholder.
`leaseStartDate`	string	Yes	Date when the lease started, if applicable, useful to calculate the remaining lease in years.
`features`	array	No	Collection of predefined property features. See the available property feature labels.
`keyFeatures`	array	Yes	Array of free text key features.
`floorplanImages`	array	No	Collection of floorplan images. Every item has 4 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the image was uploaded from if it was added via API. `alt` is the alternative text for the html image and `caption` is an optional caption you would like to display in some portals.
`energyEfficiencyRatingCurrent`	number	Yes	Current or Predicted (when new build) energy efficiency rating.
`energyEfficiencyRatingPotential`	number	Yes	Potential (when not new build) energy efficiency rating.
`environmentalImpactRatingCurrent`	number	Yes	Current or predicted (when new build) environmental impact rating.
`environmentalImpactRatingPotential`	number	Yes	Potential (when not new build) environmental impact rating.
`kid`	array	Yes	Collection of key important documents. Every item has 2 fields: `url` is the url to download the pdf file from, and save it in the KPro servers , and `caption` is an optional caption you would like to display in some portals.
`fullMarketPrice`	number	Yes	The property full market price when it is for sale.
`depositPercentage`	number	Yes	Percent to compute the lender deposit requirements when the property is for sale.
`minSharePercentage`	number	Yes	Minimum share to buy in percentage when the scheme is shared ownership (between 10 and 100).
`maxSharePercentage`	number	Yes	Maximum share to buy in percentage when the scheme is shared ownership (less or equal than 100).
`subsidisedRent`	number	Yes	It will depend on the subsidisedAsYearlyPercent value. If true the subsidised rent as a yearly percent, otherwise the monthly rent.
`subsidisedAsYearlyPercent`	boolean	No	For shared ownership properties, true is the subsidised value is expressed as a percent of the part the buyer is not going to purchase, false if the subsidised value is a fixed monthly value.
`monthlyServiceCharge`	number	Yes	When the property is for sale, the monthly bill that covers the costs of any repairs or maintenance to the structure of your building, including drainage, insurance and management charges.
`annualGroundRent`	number	Yes	The annual ground rent, made by a holder of a leasehold property to the freeholder or a superior leaseholder, as required under a lease.
`reservationFee`	number	Yes	Fee a buyer may have to pay to reserve a property for a specific period. It is not refundable, but it will usually be deducted from the purchase price if you then go on to complete the purchase of the property.
`administrationFee`	number	Yes	Fee charged by an agency to cover expenses related to record-keeping and/or other administrative costs.
`monthlyRent`	number	Yes	When the property is to rent, the monthly rent payment amount.
`rentalDeposit`	number	Yes	Security deposit to rent the property.
`minTenancyMonths`	number	Yes	Minimum tenancy term in months.
`maxTenancyMonths`	number	Yes	Maximum tenancy term in months.
`fullSpecification`	string	Yes	Details about the property that potential buyers would find useful.
`autoGenerateKid`	boolean	No	Only for Shared Ownership: The Key Information Document will be automatically generated using property information.
`sharedOwnershipType`	number	Yes	The shared ownership type when applicable. The value is a number as defined in Shared ownership types.
`estateCharge`	number	Yes	Fee to maintain the grounds and includes services such as gardening, litter picking and general grounds maintenance.
`buildingsInsurance`	number	Yes	Buildings insurance covers the cost of repairing damage to the structure of your property. Garages, sheds and fences are also covered, as well as the cost of replacing items such as pipes, cables and drains.
`managementFee`	number	Yes	Fee payable to the Manager for its day-to-day management of the Property pursuant to the Management Agreement.
`reserveFundPayment`	number	Yes	Fund set aside to cover the cost of major works or other significant items of expenditure expected in the foreseeable future, usually a period of 10-20 years.
`wardenServicesPayment`	number	Yes	Warden services/person centred services payment.
`otherMonthlyCosts`	number	Yes	Other monthly costs (e.g. alarm)
`freeholdTransferOption`	number	Yes	Only for Shared Ownership: Transfer of freehold statement. Please see the freehold transfer options.
`transferOfFreeholdReason`	string	Yes	Only for Shared Ownership: Transfer of freehold non-transfer reason, depending on the option.
`wardenServiceDetails`	string	Yes	Copy for section warden services/person centred services to generate kid documents.
`petsExtraInfo`	string	Yes	Additional information about pets, useful for kid generation.

# Import independent units

To import independent units issue a POST to /api/bulk/open/independent-units.

The payload must be similar to the JSON response when requesting the list of all independent units. A JSON object with the field data containing the collection of properties. The fields structure for every independent unit should match the one detailed above, except some fields that are not necessary because they are computed fields:

forSale
localAuthority

In the case of floorplan images, the field url is not necessary, and only the field source is mandatory from the other three fields.

Nullable fields can be omitted, but in those cases null values will be used when updating the independent unit. Although price fields are all nullables, it is because they depend on the occupancy type and the scheme group, and they could be required depending on these values. Check the section Understanding price fields.

The payload is validated before importing, and if any of the field value is invalid the whole action is cancelled and no independent unit is updated or inserted. In those cases a message with all the errors is returned.

Example

{
  "data": [
    {
      "name": "Old Farm Place",
      "externalReference": "PROP-67890",
      "schemeGroup": "shared-ownership",
      "availabilityStatus": "available",
      "propertyType": "flat",
      "newBuild": false,
      "active": true,
      "building": "",
      "street": "Old Farm Avenue",
      "town": "Sidcup",
      "postcode": "DA15 8AW",
      "handoverDate": "2018-01-23",
      "bedrooms": 2,
      "bathrooms": 1,
      "receptionRooms": 1,
      "floorArea": 64,
      "numberOfFloors": 1,
      "floor": "ground",
      "liftProvided": false,
      "furnitureStatus": "furnished",
      "tenure": "leasehold",
      "leaseYears": 125,
      "leaseStartDate": "2021-01-25",
      "features": ["off-street-parking", "communal-garden", "wheelchair-accessible"],
      "keyFeatures": ["Great location", "Excellent Transport Links", "Lots to do nearby"],
      "floorplanImages": [
        {
          "source": "https://yourserver.com/images/6575/floor-plan.png",
          "caption": null,
          "alt": "floor plan"
        }
      ],
      "energyEfficiencyRatingCurrent": null,
      "energyEfficiencyRatingPotential": null,
      "environmentalImpactRatingCurrent": null,
      "environmentalImpactRatingPotential": null,
      "autoGenerateKid": false,
      "freeholdTransferOption": 1,
      "transferOfFreeholdReason": null,
      "kid": [
        {
            "url": "https://yourserver.com/pdfs/4534/sample.pdf",
            "caption": "Important document"
        }
      ],
      "fullMarketPrice": 230000,
      "depositPercentage": 5,
      "minSharePercentage": 45,
      "maxSharePercentage": 75,
      "subsidisedRent": 431.25,
      "subsidisedAsYearlyPercent": false,
      "monthlyServiceCharge": 108.9,
      "annualGroundRent": null,
      "reservationFee": null,
      "administrationFee": null,
      "estateCharge": null,
      "buildingsInsurance": null,
      "managementFee": 20,
      "reserveFundPayment": null,
      "monthlyRent": null,
      "rentalDeposit": null,
      "minTenancyMonths": null,
      "maxTenancyMonths": null,
      "fullSpecification": "<p><strong>GENERAL</strong></p><ul><li>Open plan layout</li><li>Cool and contemporary interior</li><li>Ample storage throughout</li><li>Welcoming and modern communal areas</li><li>Bold outdoor spaces</li></ul><p><strong>KITCHEN</strong></p><ul><li>Ample workspaces</li><li>Fridge/freezer</li><li>Washer/dryer</li><li>Dishwasher</li><li>Separate electric oven and gas hob plus extractor fans</li></ul>"
    },
    {...},
    {...}
  ]
}

# REST API

The REST API endpoints are designed to keep an external system synchronized with KPro Marketing. To achieve that, the external system must store the reference identifiers returned by KPro Marketing when creating developments or properties, so the corresponding resources could be updated by using the KPro Marketing identifier.

For every type of items there will be 5 different requests:

Get all items
Get a specific item
Insert a new item
Update an existing item
Archive an item (for developments and independent units) / delete an item (for development properties)

When requesting the collection of developments and independent units, the items are returned in a paginated envelope, but the collection of properties belonging to a development are returned in a non-paginated envelope.

Paginated items can be filtered and sorted using different criteria.

# Filtering

When requesting the collection of developments and independent units the API provides several fields that can be used to filter the results, which will be specified in each section. Operators to apply filters will depend on the type of field, find below a list of all possible operators:

not: not equal
gt: greater than (for numbers, date and timestamps)
lt: less than (for numbers, date and timestamps)
gte: greater than or equal to (for numbers, date and timestamps)
lte: less than or equal to (for numbers, date and timestamps)
ltt: less than tomorrow's date, useful for datetime or timestamp fields when the filter value is a date without the time component
in: in a list of values separated by commas
notin: not in a list of values separated by commas
like: standard like operator, use * for any amount of chars and _ for a single one
regex: regular expression

Operators should be placed after the fields, separated by a dot (.). When multiple filters are specified, the AND logic operator will be used (except when using square brackets at the end of the parameter name to replace in and notin operators). When no operator is specified for a filter, the usual equal comparison is applied.

In order to filter dates and timestamps, use the ISO date format YYYY-MM-DD for dates, and if you want to include hours and minutes, use YYYY-MM-DD HH:mm. Notice that in all cases, UTC date/time is used.

Examples

To get items updated after 20-Mar-2021 10:00:

updatedAt.gte=2021-03-20 10:00

To get items where name ends with road:

name.like=*road

# Bracket option

Brackets can be used instead of values separated by commas to replace the operators in and notin.

Examples

schemeGroup.slug[]=shared-owership&schemeGroup.slug[]=help-to-buy is the same as schemeGroup.slug.in=shared-ownership,help-to-buy
schemeGroup.slug.not[]=shared-owership&schemeGroup.slug.not[]=help-to-buy is the same as schemeGroup.slug.notin=shared-ownership,help-to-buy

# Sorting

By default developments and independent units are sorted by createdAt descendent, but you can change it by using parameter sort and the field you want to sort by, separated by comma, as the value. Fields are sorted ascending, but you use the minus symbol (-) in front of any of fields to change the order to descending.

Example, to sort first by name ascending, and then by updatedAt descending, use: sort=name,-updatedAt

# Pagination

Results are paginated based on parameters page (page number, optional, default is 1) and size (maximum number of records to return per page, optional, default is 100, maximum possible value is 1000).

# Developments

When using the REST API endpoints, developments and properties are updated using different requests. So, to insert a development and all its properties, you should insert first the development and then each one of its properties. Every time a development or property is inserted you will get a response containing the inserted resource with an identifier that you should store in your system to be able to update the resource in the future.

# Get developments

To get the collection of developments issue a GET to /api/rest/open/developments, and to get a single one issue a GET to /api/rest/open/developments/{development.id}, where development.id is the development id in KPro Marketing.

Info

In KPro Marketing developments can have three different visibility status: visible, hidden and archived. When the parameter visibility is not specified, only visible and hidden developments are returned. If you want to get archived developments you will need to filter the items to return by sending QueryString parameter visibility=archived

The first endpoint will return a paginated collection of developments, while the second one will return a single object. In both cases the structure and fields for a development match.

{
  "id": 1123,
  "name": "Park Apartments",
  "developerName": "Story Homes",
  "warrantyProvider": "Peacock insurance",
  "warrantyNumber": "abc-123",
  "constructionType": "Pre-cast concrete",
  "visibility": "visible",
  "building": "Lincoln House",
  "street": "Eltham Green",
  "postcode": "SE3 9SD",
  "town": "Eltham",
  "externalReference": "DEV-12345",
  "localAuthority": {
    "name": "Greenwich",
    "county": {
      "name": "London",
      "region": "London"
    }
  },
  "insideGla": true,
  "fullCircleId": 45369,
  "siteplanImages": [
    {
      "url": "https://static.keaze.co.uk/assets/developments/1123/images/site-plan-1.png",
      "source": "https://yourserver.com/images/76854/site-plan-park-apartments.png",
      "caption": "Park apartments design",
      "alt": "Park apartments"
    }
  ],
  "activeListings": [
    {
      "name": "Park Apartments",
      "visibility": "live",
      "availabilityStatus": {
        "code": "available",
        "name": "For sale"
      },
      "schemeGroup": {
        "slug": "shared-ownership",
        "name": "Shared ownership",
        "forSale": true,
        "schemes": [
          {
            "slug": "shared-ownership",
            "name": "Shared ownership"
          }
        ]
      },
      "totalProperties": 3
    }
  ],
  "totalProperties": 3,
  "totalActiveProperties": 3,
  "updatedAt": "2021-03-08T16:53:59+00:00",
  "createdAt": "2021-03-08T16:53:59+00:00"
}

Fields

Field name	Type	Nullable	Description
`id`	number	No	Development identifier.
`name`	string	No	Name for the development.
`developerName`	string	Yes	Developer name
`warrantyProvider`	string	Yes	Warranty provider
`warrantyNumber`	string	Yes	Warranty number
`constructionType`	string	Yes	Construction type
`visibility`	string	No	visible, hidden and archived.
`building`	string	Yes	Name or number for the building.
`street`	string	Yes	The name of the road on which the development is principally adjacent.
`postcode`	string	No	The development postal area code.
`town`	string	Yes	The nearest large urban area to the development.
`externalReference`	string	Yes	Reference for users to identify the development in their system.
`localAuthority`	object	No	The local authority where the development is. It's an structure containing name for the local authority, county and region
`insideGla`	boolean	No	Whether the development is inside GLA.
`fullCircleId`	number	Yes	Full Circle development id, if applicable.
`siteplanImages`	array	No	The collection of site plan images. Every item has 4 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the image was uploaded from if it was added via API. `alt` is the alternative text for the html image and `caption` is an optional caption you would like to display in some portals.
`activeListings`	array	No	The collection of active listings the development has. See details below about the structure of the activeListing object.
`totalProperties`	number	No	Total properties in the development.
`totalActiveProperties`	number	No	Total active properties in the development.
`updatedAt`	string	No	ATOM format Date-time when the lead was updated
`createdAt`	string	No	ATOM format Date-time when the lead was created

Active listing fields

Active listings are listings related to a development which could be set as draft or live. Only one active listing per scheme group is allowed.

Field name	Type	Nullable	Description
`name`	string	No	Listing name.
`availabilityStatus`	object	No	Availability status, consisting in `code` and `name`. See availability status.
`schemeGroup`	object	No	Scheme group, consisting in an object with details about the group and the schemes in the group, usually only one. See Scheme groups.
`totalProperties`	number	No	Total properties being advertised by the listing. Active properties in the development that match the listing scheme group.

Filtering

You can use the following fields to filter:

name
visibility
building
street
postcode
town
localAuthority.name
localAuthority.county.name
localAuthority.county.region.name
updatedAt
createdAt

# Create or update a development

To create a new development issue a:

POST to /api/rest/open/developments

To update an existing development issue a:

PUT to /api/rest/open/developments/{development.id}

where {development.id} is the Id in KPro Marketing of the development to update.

When creating a new development the API will return HTTP code 201 and the response will contain a json with the new created development. Make sure to store the id to be able to add properties and update the development. When updating a development the API will return HTTP code 200 with empty response.

If there's any validation error the API will respond with HTTP code 422, and an object with attributes message and errors. Message will contain a general description of the error, and errors will contain the list of errors related to each wrong field.

Payload fields

Field name	Type	Nullable	Description
`name`	string	No	Name for the development. It should be unique among all the developments.
`developerName`	string	Yes	Developer name
`warrantyProvider`	string	Yes	Warranty provider
`warrantyNumber`	string	Yes	Warranty number
`constructionType`	string	Yes	Construction type
`building`	string	Yes	Name or number for the building.
`street`	string	Yes	The name of the road on which the development is principally adjacent.
`postcode`	string	No	The development postal area code.
`town`	string	Yes	The nearest large urban area to the development.
`externalReference`	string	Yes	Reference for users to identify the property in their system.
`fullCircleId`	number	Yes	Full Circle development id, if applicable. Do not send this field if you don't want to update it.
`siteplanImages`	array	No	Collection of site plan images for the development. Every item must be an object with 3 fields: `source` which is the url where the image is going to be uploaded from, `alt` as the alternative text for the html image and `caption`, which is an optional caption you would like to display in some portals. Only `source` is mandatory.

Example

{
  "name": "Park Apartments",
  "developerName": "Story Homes",
  "warrantyProvider": "Peacock insurance",
  "warrantyNumber": "abc-123",
  "constructionType": "Pre-cast concrete",
  "building": "Lincoln House",
  "street": "Eltham Green",
  "postcode": "SE3 9SD",
  "town": "Eltham",
  "externalReference": "DEV-12345",
  "fullCircleId": 56543,
  "siteplanImages": [
    {
      "source": "https://yourserver.com/images/76854/site-plan-park-apartments.png",
      "caption": "Park apartments design",
      "alt": "Park apartments"
    }
  ]
}

# Archive a development

To archive a development issue a:

PATCH to /api/rest/open/developments/{development.id}/archive

where {development.id} is the Id in KPro Marketing of the development to archive. Once a development is archived it cannot be restored.

# Development properties

Info

The collection of development properties doesn't have support for filtering or sorting.

# Get properties in a development

To get the collection of properties in a development issue a GET to /api/rest/open/developments/{development.id}/properties and to get a single property from a development issue a GET to /api/rest/open/developments/{development.id}/properties/{property.id}, where development.id and property.id are the development id and property id in KPro Marketing, respectively.

The first endpoint will return a non-paginated collection of properties, while the second one will return a single object. In both cases the structure and fields for a property match.

{
  "data": [
    {
      "id": 1975,
      "propertyNumber": "12",
      "externalReference": "PROP-67890",
      "schemeGroup": {
        "slug": "shared-ownership",
        "name": "Shared ownership",
        "forSale": true,
        "schemes": [
          {
            "slug": "shared-ownership",
            "name": "Shared ownership"
          }
        ]
      },
      "availabilityStatus": {
        "code": "available",
        "name": "For sale"
      },
      "propertyType": {
        "name": "Flat",
        "code": "flat",
        "group": "Flat"
      },
      "active": true,
      "forSale": true,
      "useDevelopmentAddress": true,
      "building": null,
      "street": null,
      "town": null,
      "postcode": null,
      "localAuthority": null,
      "handoverDate": "2020-10-12",
      "bedrooms": 3,
      "bathrooms": 1,
      "receptionRooms": 1,
      "floorArea": 72,
      "numberOfFloors": 1,
      "floor": {
        "code": "ground",
        "name": "Ground floor"
      },
      "liftProvided": false,
      "furnitureStatus": "furnished",
      "tenure": "leasehold",
      "leaseYears": 125,
      "features": ["driveway", "private-garden"],
      "keyFeatures": ["Great location", "Excellent Transport Links"],
      "floorplanImages": [
        {
          "url": "https://static.keaze.co.uk/assets/plots/5646/images/floor-plan.png",
          "source": "https://yourserver.com/images/4534/floor-plan.png",
          "caption": null,
          "alt": "floor plan"
        }
      ],
      "rooms": [
        {
            "name": "Kitchen",
            "additionalDetails": "Open plan",
            "units": "foot",
            "width": 18,
            "length": 24,
            "floorArea": 430
        },
        {
            "name": "Bedroom 1",
            "additionalDetails": "Ensuite bathroom",
            "units": "foot",
            "width": 16,
            "length": 15,
            "floorArea": 238
        }
      ],
      "energyEfficiencyRatingCurrent": 83,
      "environmentalImpactRatingCurrent": 86,
      "autoGenerateKid": false,
      "freeholdTransferOption": 1,
      "transferOfFreeholdReason": null,
      "kid": [
        {
            "url": "https://static.keaze.co.uk/assets/plots/5646/kids/sample.pdf",
            "source": "https://yourserver.com/pdfs/4534/sample.pdf",
            "caption": "Important document"
        }
      ],
      "fullMarketPrice": 205000,
      "depositPercentage": 5,
      "depositValue": 4612.50,
      "minSharePercentage": 45,
      "minShareValue": 92250,
      "maxSharePercentage": 75,
      "subsidisedRent": 2.75,
      "subsidisedAsYearlyPercent": true,
      "subsidisedMonthlyRent": 258,
      "monthlyServiceCharge": 88,
      "annualGroundRent": null,
      "reservationFee": null,
      "administrationFee": null,
      "estateCharge": 30,
      "buildingsInsurance": 15,
      "managementFee": 20,
      "reserveFundPayment": null,
      "maxGovernmentLoanPercent": null,
      "maxGovernmentLoanValue": null,
      "rentalDeposit": null,
      "monthlyRent": null,
      "weeklyRent": null,
      "minTenancyMonths": null,
      "maxTenancyMonths": null,
      "fullSpecifications": "<p>Modern 3-bedroom house with kitchen and dining area, fully fitted kitchen, high level double oven, hob and hood, sitting room, en suite and fitted wardrobe to the Master bedroom and parking</p>",
      "fullCircleId": 54632,
      "updatedAt": "2021-03-08T17:23:01+00:00",
      "createdAt": "2021-03-08T17:17:03+00:00"
    },
  ...
  ]
}

Fields

Field name	Type	Nullable	Description
`id`	number	No	Property identifier in KPro Marketing
`propertyNumber`	string	No	Alphanumeric value that identifies the property in the development. It should be unique in the scope of its development.
`externalReference`	string	Yes	Reference for users to identify the property in their system.
`schemeGroup`	object	No	Scheme groups under the property is sold or rented.
`availabilityStatus`	object	No	One of the four possible availability status, regardless the property is for sale or to rent.
`propertyType`	object	No	Describe the type of property.
`active`	boolean	No	Whether the property is active or not.
`forSale`	boolean	No	Whether the property is for sale (true) or to rent (false).
`useDevelopmentAddress`	boolean	No	Whether the address come from development. If false, the next 5 fields will be null.
`building`	string	Yes	The building name or number where the property belongs.
`street`	string	Yes	The name of the road on which the property is principally adjacent.
`town`	string	Yes	The nearest large urban area to the property.
`postcode`	string	Yes	The property postal area code.
`localAuthority`	object	Yes	The local authority name where the property is.
`handoverDate`	string	Yes	Property handover date.
`bedrooms`	number	No	The total number of bedrooms within the property.
`bathrooms`	number	No	The number of bathrooms within the property.
`receptionRooms`	number	No	The number of reception rooms within the property.
`floorArea`	number	Yes	Area occupied by the property floor in square meters.
`numberOfFloors`	number	No	How many floors the property occupies or consists of. Usually 1, but most of detached and semi-detached houses consist of 2 floors.
`floor`	object	No	The property entrance floor. Please see the floor labels.
`liftProvided`	boolean	Yes	Lift provided
`furnitureStatus`	string	No	Whether the property is furnished, part-furnished or unfurnished. See the furniture status labels.
`tenure`	string	No	leasehold or freehold
`leaseYears`	number	Yes	When tenure is leasehold, the number of years to use the home from the freeholder.
`features`	array	No	Collection of predefined property features. See the available property feature labels.
`keyFeatures`	array	Yes	Array of free text key features.
`floorplanImages`	array	No	Collection of floorplan images. Every item has 4 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the image was uploaded from if it was added via API. `alt` is the alternative text for the html image and `caption` is an optional caption you would like to display in some portals.
`rooms`	array	No	Collection of property rooms. Every item has: `name`, `additionalDetails`, `units` (foot or metre), `width`, `length` and `floorArea`. Name and additional details are free texts, up to 255 chars length, while width, length and floorArea are numbers expressed in the provided units. Only name and units are required.
`energyEfficiencyRatingCurrent`	number	Yes	Predicted energy efficiency rating.
`environmentalImpactRatingCurrent`	number	Yes	Predicted environmental impact rating.
`kid`	array	No	Collection of key important documents. Every item has 3 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the file was uploaded from if it was added via API. `caption` is an optional caption you would like to display in some portals.
`fullMarketPrice`	number	Yes	The property full market price when it is for sale.
`depositPercentage`	number	Yes	Percent to compute the lender deposit requirements when the property is for sale.
`depositValue`	number	Yes	The minimum deposit value computed from the percent.
`isSharedOwnership`	boolean	No	The property scheme is shared ownership, so there's a share to buy and the rest to rent.
`minSharePercentage`	number	Yes	Minimum share to buy in percentage when the scheme is shared ownership (between 10 and 100).
`minShareValue`	number	Yes	Minimum share value computed from `minSharePercentage`.
`maxSharePercentage`	number	Yes	Maximum share to buy in percentage when the scheme is shared ownership.
`subsidisedRent`	number	Yes	It will depend on the subsidisedAsYearlyPercent value. If true the subsidised rent as a yearly percent, otherwise the monthly rent.
`subsidisedAsYearlyPercent`	boolean	No	For shared ownership properties, true is the subsidised value is expressed as a percent of the part the buyer is not going to purchase, false if the subsidised value is a fixed monthly value.
`subsidisedMonthlyRent`	number	Yes	The minimum amount to pay in value monthly for the subsidised part. It's computed from previous 2 fields.
`maxGovernmentLoanPercent`	number	Yes	Depending on the scheme, eligible buyers could receive a government loan. In such a case, this value is the maximum government loan percent as set up in KPro Marketing.
`maxGovernmentLoanValue`	number	Yes	The maximum government loan value, computed from the percent.
`monthlyServiceCharge`	number	Yes	When the property is for sale, the monthly bill that covers the costs of any repairs or maintenance to the structure of your building, including drainage, insurance and management charges.
`annualGroundRent`	number	Yes	The annual ground rent, made by a holder of a leasehold property to the freeholder or a superior leaseholder, as required under a lease.
`reservationFee`	number	Yes	Fee a buyer may have to pay to reserve a property for a specific period. It is not refundable, but it will usually be deducted from the purchase price if you then go on to complete the purchase of the property.
`administrationFee`	number	Yes	Fee charged by an agency to cover expenses related to record-keeping and/or other administrative costs.
`monthlyRent`	number	Yes	When the property is to rent, the monthly rent payment amount.
`rentalDeposit`	number	Yes	Security deposit to rent the property.
`minTenancyMonths`	number	Yes	Minimum tenancy term in months.
`maxTenancyMonths`	number	Yes	Maximum tenancy term in months.
`fullSpecification`	string	Yes	Details about the property that potential buyers would find useful.
`fullCircleId`	number	Yes	Full Circle property id, if applicable.
`autoGenerateKid`	boolean	No	Only for Shared Ownership: The Key Information Document will be automatically generated using property information.
`sharedOwnershipType`	number	Yes	The shared ownership type when applicable. The value is a number as defined in Shared ownership types.
`estateCharge`	number	Yes	Fee to maintain the grounds and includes services such as gardening, litter picking and general grounds maintenance.
`buildingsInsurance`	number	Yes	Buildings insurance covers the cost of repairing damage to the structure of your property. Garages, sheds and fences are also covered, as well as the cost of replacing items such as pipes, cables and drains.
`managementFee`	number	Yes	Fee payable to the Manager for its day-to-day management of the Property pursuant to the Management Agreement.
`reserveFundPayment`	number	Yes	Fund set aside to cover the cost of major works or other significant items of expenditure expected in the foreseeable future, usually a period of 10-20 years.
`wardenServicesPayment`	number	Yes	Warden services/person centred services payment.
`otherMonthlyCosts`	number	Yes	Other monthly costs (e.g. alarm)
`freeholdTransferOption`	number	Yes	Only for Shared Ownership: Transfer of freehold statement. Please see the freehold transfer options.
`transferOfFreeholdReason`	string	Yes	Only for Shared Ownership: Transfer of freehold non-transfer reason, depending on the option.
`wardenServiceDetails`	string	Yes	Copy for section warden services/person centred services to generate kid documents.
`petsExtraInfo`	string	Yes	Additional information about pets, useful for kid generation.

# Create or update a property in a development

To create a new property in an existing development, issue a:

POST to /api/rest/open/developments/{development.id}/properties

To update an existing property issue a:

PUT to /api/rest/open/developments/{development.id}/properties/{property.id}

where {development.id} is the Id in KPro Marketing of the development where the property belongs, and {property.id} id the Id in KPro Marketing of the property to update.

Payload fields

The fields to update or insert a new property are basically the same returned when requesting a resource, but removing all computed fields, and most object fields only require a string that matches the code or slug.

Field name	Type	Nullable	Description
`propertyNumber`	string	No	Alphanumeric value that identifies the property in the development. It should be unique in the scope of its development.
`externalReference`	string	Yes	Reference for users to identify the property in their system.
`schemeGroup`	string	No	Label for the Scheme groups under the property is sold or rented.
`availabilityStatus`	string	No	One of the four possible availability status, regardless the property is for sale or to rent.
`propertyType`	string	No	Describe the type of property.
`active`	boolean	No	Whether the property is active or not.
`useDevelopmentAddress`	boolean	No	Whether the address come from development. If false, the next 5 fields will be null.
`building`	string	Yes	The building name or number where the property belongs.
`street`	string	Yes	The name of the road on which the property is principally adjacent.
`town`	string	Yes	The nearest large urban area to the property.
`postcode`	string	Yes	The property postal area code.
`localAuthority`	object	Yes	The local authority name where the property is.
`handoverDate`	string	Yes	Property handover date.
`bedrooms`	number	No	The total number of bedrooms within the property.
`bathrooms`	number	No	The number of bathrooms within the property.
`receptionRooms`	number	No	The number of reception rooms within the property.
`floorArea`	number	Yes	Area occupied by the property floor in square meters.
`numberOfFloors`	number	No	How many floors the property occupies or consists of. Usually 1, but most of detached and semi-detached houses consist of 2 floors.
`floor`	string	No	The property entrance floor. Please see the floor labels.
`liftProvided`	boolean	Yes	Lift provided
`furnitureStatus`	string	No	Whether the property is furnished, part-furnished or unfurnished. See the furniture status labels.
`tenure`	string	No	leasehold or freehold
`leaseYears`	number	Yes	When tenure is leasehold, the number of years to use the home from the freeholder.
`features`	array	No	Collection of predefined property features. See the available property feature labels.
`keyFeatures`	array	Yes	Array of free text key features.
`floorplanImages`	array	No	Collection of floorplan images. Every item has 3 fields: `source` is the url where the image is going to be uploaded from , `alt` is the alternative text for the html image and `caption` is an optional caption you would like to display in some portals. Only source is mandatory.
`rooms`	array	No	Collection of property rooms. Every item has: `name`, `additionalDetails`, `units` (foot or metre), `width`, `length` and `floorArea`. Name and additional details are free texts, up to 255 chars length, while width, length and floorArea are numbers expressed in the provided units. Only name and units are required. When updating properties, the value in name is used to identify existing rooms, updating matching records in the database.
`energyEfficiencyRatingCurrent`	number	Yes	Predicted energy efficiency rating.
`environmentalImpactRatingCurrent`	number	Yes	Predicted environmental impact rating.
`kid`	array	Yes	Collection of key important documents. Every item has 2 fields: `url` is the url to download the pdf file from, and save it in the KPro servers , and `caption` is an optional caption you would like to display in some portals.
`fullMarketPrice`	number	Yes	The property full market price when it is for sale.
`depositPercentage`	number	Yes	Percent to compute the lender deposit requirements when the property is for sale.
`minSharePercentage`	number	Yes	Minimum share to buy in percentage when the scheme is shared ownership (between 10 and 100).
`maxSharePercentage`	number	Yes	Maximum share to buy in percentage when the scheme is shared ownership (less or equal than 100).
`subsidisedRent`	number	Yes	It will depend on the subsidisedAsYearlyPercent value. If true the subsidised rent as a yearly percent, otherwise the monthly rent.
`subsidisedAsYearlyPercent`	boolean	No	For shared ownership properties, true is the subsidised value is expressed as a percent of the part the buyer is not going to purchase, false if the subsidised value is a fixed monthly value.
`monthlyServiceCharge`	number	Yes	When the property is for sale, the monthly bill that covers the costs of any repairs or maintenance to the structure of your building, including drainage, insurance and management charges.
`annualGroundRent`	number	Yes	The annual ground rent, made by a holder of a leasehold property to the freeholder or a superior leaseholder, as required under a lease.
`reservationFee`	number	Yes	Fee a buyer may have to pay to reserve a property for a specific period. It is not refundable, but it will usually be deducted from the purchase price if you then go on to complete the purchase of the property.
`administrationFee`	number	Yes	Fee charged by an agency to cover expenses related to record-keeping and/or other administrative costs.
`monthlyRent`	number	Yes	When the property is to rent, the monthly rent payment amount.
`rentalDeposit`	number	Yes	Security deposit to rent the property.
`minTenancyMonths`	number	Yes	Minimum tenancy term in months.
`maxTenancyMonths`	number	Yes	Maximum tenancy term in months.
`fullSpecification`	string	Yes	Details about the property that potential buyers would find useful.
`fullCircleId`	number	Yes	Full Circle property id, if applicable. Do not send this field if you don't want to update it.
`autoGenerateKid`	boolean	No	Only for Shared Ownership: The Key Information Document will be automatically generated using property information.
`sharedOwnershipType`	number	Yes	The shared ownership type when applicable. The value is a number as defined in Shared ownership types.
`estateCharge`	number	Yes	Fee to maintain the grounds and includes services such as gardening, litter picking and general grounds maintenance.
`buildingsInsurance`	number	Yes	Buildings insurance covers the cost of repairing damage to the structure of your property. Garages, sheds and fences are also covered, as well as the cost of replacing items such as pipes, cables and drains.
`managementFee`	number	Yes	Fee payable to the Manager for its day-to-day management of the Property pursuant to the Management Agreement.
`reserveFundPayment`	number	Yes	Fund set aside to cover the cost of major works or other significant items of expenditure expected in the foreseeable future, usually a period of 10-20 years.
`wardenServicesPayment`	number	Yes	Warden services/person centred services payment.
`otherMonthlyCosts`	number	Yes	Other monthly costs (e.g. alarm)
`freeholdTransferOption`	number	Yes	Only for Shared Ownership: Transfer of freehold statement. Please see the freehold transfer options.
`transferOfFreeholdReason`	string	Yes	Only for Shared Ownership: Transfer of freehold non-transfer reason, depending on the option.
`wardenServiceDetails`	string	Yes	Copy for section warden services/person centred services to generate kid documents.
`petsExtraInfo`	string	Yes	Additional information about pets, useful for kid generation.

Example

{
    "propertyNumber": "12",
    "externalReference": "PROP-67890",
    "schemeGroup": "shared-ownership",
    "availabilityStatus": "available",
    "propertyType": "flat",
    "active": true,
    "useDevelopmentAddress": true,
    "building": null,
    "street": null,
    "town": null,
    "postcode": null,
    "handoverDate": "2020-10-12",
    "bedrooms": 3,
    "bathrooms": 1,
    "receptionRooms": 1,
    "floorArea": 72,
    "numberOfFloors": 1,
    "floor": "ground",
    "liftProvided": false,
    "furnitureStatus": "furnished",
    "tenure": "leasehold",
    "leaseYears": 125,
    "leaseStartDate": "2021-01-25",
    "features": ["driveway", "private-garden"],
    "keyFeatures": ["Great location", "Excellent Transport Links"],
    "floorplanImages": [
        {
        "source": "https://yourserver.com/images/4534/floor-plan.png",
        "caption": null,
        "alt": "floor plan"
        }
    ],
    "rooms": [
        {
            "name": "Kitchen",
            "additionalDetails": "Open plan",
            "units": "foot",
            "width": 18,
            "length": 24,
            "floorArea": 430
        },
        {
            "name": "Bedroom 1",
            "additionalDetails": "Ensuite bathroom",
            "units": "foot",
            "width": 16,
            "length": 15,
            "floorArea": 238
        }
    ],
    "energyEfficiencyRatingCurrent": 83,
    "environmentalImpactRatingCurrent": 86,
    "autoGenerateKid": false,
    "freeholdTransferOption": 1,
    "transferOfFreeholdReason": null,
    "kid": [
        {
            "url": "https://yourserver.com/pdfs/4534/sample.pdf",
            "caption": "Important document"
        }
    ],
    "fullMarketPrice": 205000,
    "depositPercentage": 5,
    "minSharePercentage": 45,
    "maxSharePercentage": 75,
    "subsidisedRent": 2.75,
    "subsidisedAsYearlyPercent": true,
    "monthlyServiceCharge": 88,
    "annualGroundRent": null,
    "reservationFee": null,
    "administrationFee": null,
    "estateCharge": 30,
    "buildingsInsurance": 15,
    "managementFee": 20,
    "reserveFundPayment": null,
    "rentalDeposit": null,
    "monthlyRent": null,
    "weeklyRent": null,
    "minTenancyMonths": null,
    "maxTenancyMonths": null,
    "fullSpecifications": "<p>Modern 3-bedroom house with kitchen and dining area, fully fitted kitchen, high level double oven, hob and hood, sitting room, en suite and fitted wardrobe to the Master bedroom and parking</p>",
    "fullCircleId": 453642
}

# Delete a property in a development

To delete an existing property issue a DELETE to /api/rest/open/developments/{development.id}/properties/{property.id}, where {development.id} is the Id in KPro Marketing of the development where the property belongs, and {property.id} id the Id in KPro Marketing of the property to delete. This process is irreversible.

When the action was successful, HTTP code 200 is returned, otherwise an HTTP code in the range of 400 is returned, along with an error message.

# Independent units

Independent units are intended for properties that you want to manage independently (not as part of a development) or are resale properties.

# Get independent units

To get all the independent units issue a GET to /api/rest/open/independent-units and to get a single one issue a GET to /api/rest/open/independent-units/{property.id}, where property.id is the independent unit id in KPro Marketing.

Info

In KPro Marketing independent units can have three different visibility status: visible, hidden and archived. When the parameter visibility is not specified, only visible and hidden independent units are returned. If you want to get archived independent units you will need to filter the items to return by sending QueryString parameter visibility=archived

The first endpoint will return a paginated collection of properties, while the second one will return a single object. In both cases the structure and fields for a independent unit match.

Independent units share the same fields structure as development properties, except some minor differences:

They use field name instead propertyNumber
They always require address fields: building, street, town and postcode
They require field newBuild to specify if it's a new-build property or not
Besides current energy efficiency rating and current environmental impact rating, potential values can be specified for resale properties.

{
  "data": [
    {
      "id": 59984,
      "name": "Old Farm Place",
      "externalReference": "PROP-67890",
      "visibility": "visible",
      "schemeGroup": {
        "slug": "shared-ownership",
        "name": "Shared ownership",
        "forSale": true,
        "schemes": [
          {
            "slug": "shared-ownership",
            "name": "Shared ownership"
          }
        ]
      },
      "availabilityStatus": {
        "code": "available",
        "name": "For sale"
      },
      "propertyType": {
        "name": "Flat",
        "code": "flat",
        "group": "Flat"
      },
      "newBuild": false,
      "active": true,
      "forSale": true,
      "building": "",
      "street": "Old Farm Avenue",
      "town": "Sidcup",
      "postcode": "DA15 8AW",
      "localAuthority": {
        "name": "Bexley",
        "county": {
          "name": "London",
          "region": "London"
        }
      },
      "handoverDate": "2018-01-23",
      "bedrooms": 2,
      "bathrooms": 1,
      "receptionRooms": 1,
      "floorArea": 64,
      "numberOfFloors": 1,
      "floor": {
        "code": "ground",
        "name": "Ground floor"
      },
      "liftProvided": false,
      "furnitureStatus": "furnished",
      "tenure": "leasehold",
      "leaseYears": 125,
      "leaseStartDate": "2021-01-25",
      "features": ["off-street-parking", "communal-garden", "wheelchair-accessible"],
      "keyFeatures": ["Great location", "Excellent Transport Links", "Lots to do nearby"],
      "floorplanImages": [
        {
          "url": "https://static.keaze.co.uk/assets/properties/4576/images/floor-plan.png",
          "source": "https://yourserver.com/images/6575/floor-plan.png",
          "caption": null,
          "alt": "floor plan"
        }
      ],
      "rooms": [
        {
            "name": "Kitchen",
            "additionalDetails": "Open plan",
            "units": "foot",
            "width": 18,
            "length": 24,
            "floorArea": 430
        },
        {
            "name": "Bedroom 1",
            "additionalDetails": "Ensuite bathroom",
            "units": "foot",
            "width": 16,
            "length": 15,
            "floorArea": 238
        }
      ],
      "energyEfficiencyRatingCurrent": 82,
      "energyEfficiencyRatingPotential": 90,
      "environmentalImpactRatingCurrent": 86,
      "environmentalImpactRatingPotential": 92,
      "autoGenerateKid": false,
      "freeholdTransferOption": 1,
      "transferOfFreeholdReason": null,
      "kid": [
        {
            "url": "https://static.keaze.co.uk/assets/plots/5646/kids/sample.pdf",
            "source": "https://yourserver.com/pdfs/4534/sample.pdf",
            "caption": "Important document"
        }
      ],
      "fullMarketPrice": 230000,
      "depositPercentage": 5,
      "depositValue": 5175,
      "isSharedOwnership": true,
      "minSharePercentage": 45,
      "minShareValue": 103500,
      "maxSharePercentage": 75,
      "subsidisedRent": 431.25,
      "subsidisedAsYearlyPercent": false,
      "subsidisedMonthlyRent": 431.25,
      "maxGovernmentLoanPercent": null,
      "maxGovernmentLoanValue": null,
      "monthlyServiceCharge": 108.9,
      "annualGroundRent": null,
      "reservationFee": null,
      "administrationFee": null,
      "estateCharge": 30,
      "buildingsInsurance": 15,
      "managementFee": 20,
      "reserveFundPayment": null,
      "monthlyRent": null,
      "rentalDeposit": null,
      "minTenancyMonths": null,
      "maxTenancyMonths": null,
      "fullSpecification": "<p><strong>GENERAL</strong></p><ul><li>Open plan layout</li><li>Cool and contemporary interior</li><li>Ample storage throughout</li><li>Welcoming and modern communal areas</li><li>Bold outdoor spaces</li></ul><p><strong>KITCHEN</strong></p><ul><li>Ample workspaces</li><li>Fridge/freezer</li><li>Washer/dryer</li><li>Dishwasher</li><li>Separate electric oven and gas hob plus extractor fans</li></ul>",
      "fullCircleId": 45373,
      "updatedAt": "2021-01-29T15:31:48+00:00",
      "createdAt": "2021-01-29T15:26:28+00:00"
    },
    ...
  ]
}

Fields

Field name	Type	Nullable	Description
`id`	number	No	Independent unit identifier in KPro Marketing
`name`	string	No	Name for the independent unit. It should be unique among all the independent units.
`externalReference`	string	Yes	Reference for users to identify the property in their system.
`visibility`	string	No	visible, hidden and archived.
`schemeGroup`	object	No	Scheme groups under the property is sold or rented.
`availabilityStatus`	object	No	One of the four possible availability status, regardless the property is for sale or to rent.
`propertyType`	object	No	Describe the type of property.
`newBuild`	boolean	No	Whether the property is new build or not.
`active`	boolean	No	Whether the property is active or not.
`forSale`	boolean	No	Whether the property is for sale (true) or to rent (false).
`building`	string	Yes	The building name or number where the property belongs.
`street`	string	Yes	The name of the road on which the property is principally adjacent.
`town`	string	Yes	The nearest large urban area to the property.
`postcode`	string	Yes	The property postal area code.
`localAuthority`	object	Yes	The local authority name where the property is.
`handoverDate`	string	Yes	Property handover date.
`bedrooms`	number	No	The total number of bedrooms within the property.
`bathrooms`	number	No	The number of bathrooms within the property.
`receptionRooms`	number	No	The number of reception rooms within the property.
`floorArea`	number	Yes	Area occupied by the property floor in square meters.
`numberOfFloors`	number	No	How many floors the property occupies or consists of. Usually 1, but most of detached and semi-detached houses consist of 2 floors.
`floor`	object	No	The property entrance floor. Please see the floor labels.
`liftProvided`	boolean	Yes	Lift provided
`furnitureStatus`	string	No	Whether the property is furnished, part-furnished or unfurnished. See the furniture status labels.
`tenure`	string	No	leasehold or freehold
`leaseYears`	number	Yes	When tenure is leasehold, the number of years to use the home from the freeholder.
`leaseStartDate`	string	Yes	Date when the lease started, if applicable, useful to calculate the remaining lease in years.
`features`	array	No	Collection of predefined property features. See the available property feature labels.
`keyFeatures`	array	Yes	Array of free text key features.
`floorplanImages`	array	No	Collection of floorplan images. Every item has 4 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the image was uploaded from if it was added via API. `alt` is the alternative text for the html image and `caption` is an optional caption you would like to display in some portals.
`rooms`	array	No	Collection of property rooms. Every item has: `name`, `additionalDetails`, `units` (foot or metre), `width`, `length` and `floorArea`. Name and additional details are free texts, up to 255 chars length, while width, length and floorArea are numbers expressed in the provided units. Only name and units are required.
`energyEfficiencyRatingCurrent`	number	Yes	Current energy efficiency rating (Predicted if new build).
`energyEfficiencyRatingPotential`	number	Yes	Potential energy efficiency rating when not new build.
`environmentalImpactRatingCurrent`	number	Yes	Current environmental impact rating (Predicted if new build).
`environmentalImpactRatingPotential`	number	Yes	Potential environmental impact rating when not new build.
`kid`	array	No	Collection of key important documents. Every item has 3 fields: `url` is the url in KPro Marketing servers, and `source` is the url where the file was uploaded from if it was added via API. `caption` is an optional caption you would like to display in some portals.
`fullMarketPrice`	number	Yes	The property full market price when it is for sale.
`depositPercentage`	number	Yes	Percent to compute the lender deposit requirements when the property is for sale.
`depositValue`	number	Yes	The minimum deposit value computed from the percent.
`isSharedOwnership`	boolean	No	The property scheme is shared ownership, so there's a share to buy and the rest to rent.
`minSharePercentage`	number	Yes	Minimum share to buy in percentage when the scheme is shared ownership (between 10 and 100).
`minShareValue`	number	Yes	Minimum share value computed from `minSharePercentage`.
`maxSharePercentage`	number	Yes	Maximum share to buy in percentage when the scheme is shared ownership.
`subsidisedRent`	number	Yes	It will depend on the subsidisedAsYearlyPercent value. If true the subsidised rent as a yearly percent, otherwise the monthly rent.
`subsidisedAsYearlyPercent`	boolean	No	For shared ownership properties, true is the subsidised value is expressed as a percent of the part the buyer is not going to purchase, false if the subsidised value is a fixed monthly value.
`subsidisedMonthlyRent`	number	Yes	The minimum amount to pay in value monthly for the subsidised part. It's computed from previous 2 fields.
`maxGovernmentLoanPercent`	number	Yes	Depending on the scheme, eligible buyers could receive a government loan. In such a case, this value is the maximum government loan percent as set up in KPro Marketing.
`maxGovernmentLoanValue`	number	Yes	The maximum government loan value, computed from the percent.
`monthlyServiceCharge`	number	Yes	When the property is for sale, the monthly bill that covers the costs of any repairs or maintenance to the structure of your building, including drainage, insurance and management charges.
`annualGroundRent`	number	Yes	The annual ground rent, made by a holder of a leasehold property to the freeholder or a superior leaseholder, as required under a lease.
`reservationFee`	number	Yes	Fee a buyer may have to pay to reserve a property for a specific period. It is not refundable, but it will usually be deducted from the purchase price if you then go on to complete the purchase of the property.
`administrationFee`	number	Yes	Fee charged by an agency to cover expenses related to record-keeping and/or other administrative costs.
`monthlyRent`	number	Yes	When the property is to rent, the monthly rent payment amount.
`rentalDeposit`	number	Yes	Security deposit to rent the property.
`minTenancyMonths`	number	Yes	Minimum tenancy term in months.
`maxTenancyMonths`	number	Yes	Maximum tenancy term in months.
`fullSpecification`	string	Yes	Details about the property that potential buyers would find useful.
`fullCircleId`	number	Yes	Full Circle property id, if applicable.
`autoGenerateKid`	boolean	No	Only for Shared Ownership: The Key Information Document will be automatically generated using property information.
`sharedOwnershipType`	number	Yes	The shared ownership type when applicable. The value is a number as defined in Shared ownership types.
`estateCharge`	number	Yes	Fee to maintain the grounds and includes services such as gardening, litter picking and general grounds maintenance.
`buildingsInsurance`	number	Yes	Buildings insurance covers the cost of repairing damage to the structure of your property. Garages, sheds and fences are also covered, as well as the cost of replacing items such as pipes, cables and drains.
`managementFee`	number	Yes	Fee payable to the Manager for its day-to-day management of the Property pursuant to the Management Agreement.
`reserveFundPayment`	number	Yes	Fund set aside to cover the cost of major works or other significant items of expenditure expected in the foreseeable future, usually a period of 10-20 years.
`wardenServicesPayment`	number	Yes	Warden services/person centred services payment.
`otherMonthlyCosts`	number	Yes	Other monthly costs (e.g. alarm)
`freeholdTransferOption`	number	Yes	Only for Shared Ownership: Transfer of freehold statement. Please see the freehold transfer options.
`transferOfFreeholdReason`	string	Yes	Only for Shared Ownership: Transfer of freehold non-transfer reason, depending on the option.
`wardenServiceDetails`	string	Yes	Copy for section warden services/person centred services to generate kid documents.
`petsExtraInfo`	string	Yes	Additional information about pets, useful for kid generation.

Filtering

You can use the following fields to filter:

name
visibility
schemeGroup.name
schemeGroup.slug
availabilityStatus.name
availabilityStatus.code
propertyType.name
propertyType.code
newBuild
active
building
street
postcode
town
localAuthority.name
localAuthority.county.name
localAuthority.county.region.name
bedrooms
bathrooms
receptionRooms
floor.name
floor.code
fullMarketPrice
monthlyRent
updatedAt
createdAt

# Create or update an independent unit

To create a new independent unit, issue a:

POST to /api/rest/open/independent-units

To update an existing independent unit issue a:

PUT to /api/rest/open/independent-units/{property.id}, where property.id is the independent unit id in KPro Marketing.

Payload fields

Field name	Type	Nullable	Description
`name`	string	No	Name for the independent unit. It should be unique among all the independent units.
`externalReference`	string	Yes	Reference for users to identify the property in their system.
`schemeGroup`	string	No	Label for the Scheme groups under the property is sold or rented.
`availabilityStatus`	string	No	One of the four possible availability status, regardless the property is for sale or to rent.
`propertyType`	string	No	Describe the type of property.
`newBuild`	boolean	No	Whether the property is new build or not.
`active`	boolean	No	Whether the property is active or not.
`building`	string	Yes	The building name or number where the property belongs.
`street`	string	Yes	The name of the road on which the property is principally adjacent.
`town`	string	Yes	The nearest large urban area to the property.
`postcode`	string	No	The property postal area code.
`handoverDate`	string	Yes	Property handover date.
`bedrooms`	number	No	The total number of bedrooms within the property.
`bathrooms`	number	No	The number of bathrooms within the property.
`receptionRooms`	number	No	The number of reception rooms within the property.
`floorArea`	number	Yes	Area occupied by the property floor in square meters.
`numberOfFloors`	number	No	How many floors the property occupies or consists of. Usually 1, but most of detached and semi-detached houses consist of 2 floors.
`floor`	string	No	The property entrance floor. Please see the floor labels.
`liftProvided`	boolean	Yes	Lift provided
`furnitureStatus`	string	No	Whether the property is furnished, part-furnished or unfurnished. See the furniture status labels.
`tenure`	string	No	leasehold or freehold
`leaseYears`	number	Yes	When tenure is leasehold, the number of years to use the home from the freeholder.
`leaseStartDate`	string	Yes	Date when the lease started, if applicable, useful to calculate the remaining lease in years.
`features`	array	No	Collection of predefined property features. See the available property feature labels.
`keyFeatures`	array	Yes	Array of free text key features.
`floorplanImages`	array	No	Collection of floorplan images. Every item has 3 fields: `source` is the url where the image will be uploaded from. `alt` is the alternative text for the html image and `caption` is an optional caption you would like to display in some portals. Only source is mandatory.
`rooms`	array	No	Collection of property rooms. Every item has: `name`, `additionalDetails`, `units` (foot or metre), `width`, `length` and `floorArea`. Name and additional details are free texts, up to 255 chars length, while width, length and floorArea are numbers expressed in the provided units. Only name and units are required. When updating properties, the value in name is used to identify existing rooms, updating matching records in the database.
`energyEfficiencyRatingCurrent`	number	Yes	Current energy efficiency rating (Predicted if new build).
`energyEfficiencyRatingPotential`	number	Yes	Potential energy efficiency rating when not new build.
`environmentalImpactRatingCurrent`	number	Yes	Current environmental impact rating (Predicted if new build).
`environmentalImpactRatingPotential`	number	Yes	Potential environmental impact rating when not new build.
`kid`	array	Yes	Collection of key important documents. Every item has 2 fields: `url` is the url to download the pdf file from, and save it in the KPro servers , and `caption` is an optional caption you would like to display in some portals.
`fullMarketPrice`	number	Yes	The property full market price when it is for sale.
`depositPercentage`	number	Yes	Percent to compute the lender deposit requirements when the property is for sale.
`minSharePercentage`	number	Yes	Minimum share to buy in percentage when the scheme is shared ownership (between 10 and 100).
`maxSharePercentage`	number	Yes	Maximum share to buy in percentage when the scheme is shared ownership (less or equal than 100).
`subsidisedRent`	number	Yes	It will depend on the subsidisedAsYearlyPercent value. If true the subsidised rent as a yearly percent, otherwise the monthly rent.
`subsidisedAsYearlyPercent`	boolean	No	For shared ownership properties, true is the subsidised value is expressed as a percent of the part the buyer is not going to purchase, false if the subsidised value is a fixed monthly value.
`monthlyServiceCharge`	number	Yes	When the property is for sale, the monthly bill that covers the costs of any repairs or maintenance to the structure of your building, including drainage, insurance and management charges.
`annualGroundRent`	number	Yes	The annual ground rent, made by a holder of a leasehold property to the freeholder or a superior leaseholder, as required under a lease.
`reservationFee`	number	Yes	Fee a buyer may have to pay to reserve a property for a specific period. It is not refundable, but it will usually be deducted from the purchase price if you then go on to complete the purchase of the property.
`administrationFee`	number	Yes	Fee charged by an agency to cover expenses related to record-keeping and/or other administrative costs.
`monthlyRent`	number	Yes	When the property is to rent, the monthly rent payment amount.
`rentalDeposit`	number	Yes	Security deposit to rent the property.
`minTenancyMonths`	number	Yes	Minimum tenancy term in months.
`maxTenancyMonths`	number	Yes	Maximum tenancy term in months.
`fullSpecification`	string	Yes	Details about the property that potential buyers would find useful.
`fullCircleId`	number	Yes	Full Circle property id, if applicable. Do not send this field if you don't want to update it.
`autoGenerateKid`	boolean	No	Only for Shared Ownership: The Key Information Document will be automatically generated using property information.
`sharedOwnershipType`	number	Yes	The shared ownership type when applicable. The value is a number as defined in Shared ownership types.
`estateCharge`	number	Yes	Fee to maintain the grounds and includes services such as gardening, litter picking and general grounds maintenance.
`buildingsInsurance`	number	Yes	Buildings insurance covers the cost of repairing damage to the structure of your property. Garages, sheds and fences are also covered, as well as the cost of replacing items such as pipes, cables and drains.
`managementFee`	number	Yes	Fee payable to the Manager for its day-to-day management of the Property pursuant to the Management Agreement.
`reserveFundPayment`	number	Yes	Fund set aside to cover the cost of major works or other significant items of expenditure expected in the foreseeable future, usually a period of 10-20 years.
`wardenServicesPayment`	number	Yes	Warden services/person centred services payment.
`otherMonthlyCosts`	number	Yes	Other monthly costs (e.g. alarm)
`freeholdTransferOption`	number	Yes	Only for Shared Ownership: Transfer of freehold statement. Please see the freehold transfer options.
`transferOfFreeholdReason`	string	Yes	Only for Shared Ownership: Transfer of freehold non-transfer reason, depending on the option.
`wardenServiceDetails`	string	Yes	Copy for section warden services/person centred services to generate kid documents.
`petsExtraInfo`	string	Yes	Additional information about pets, useful for kid generation.

Example

{
    "name": "Old Farm Place",
    "externalReference": "PROP-67890",
    "schemeGroup": "shared-ownership",
    "availabilityStatus": "available",
    "propertyType": "flat",
    "newBuild": false,
    "active": true,
    "building": "",
    "street": "Old Farm Avenue",
    "town": "Sidcup",
    "postcode": "DA15 8AW",
    "handoverDate": "2018-01-23",
    "bedrooms": 2,
    "bathrooms": 1,
    "receptionRooms": 1,
    "floorArea": 64,
    "numberOfFloors": 1,
    "floor": "ground",
    "liftProvided": false,
    "furnitureStatus": "furnished",
    "tenure": "leasehold",
    "leaseYears": 125,
    "leaseStartDate": "2021-01-25",
    "features": ["off-street-parking", "communal-garden", "wheelchair-accessible"],
    "keyFeatures": ["Great location", "Excellent Transport Links", "Lots to do nearby"],
    "floorplanImages": [
        {
            "source": "https://yourserver.com/images/6575/floor-plan.png",
            "caption": null,
            "alt": "floor plan"
        }
    ],
    "rooms": [
        {
            "name": "Kitchen",
            "additionalDetails": "Open plan",
            "units": "foot",
            "width": 18,
            "length": 24,
            "floorArea": 430
        },
        {
            "name": "Bedroom 1",
            "additionalDetails": "Ensuite bathroom",
            "units": "foot",
            "width": 16,
            "length": 15,
            "floorArea": 238
        }
    ],
    "energyEfficiencyRatingCurrent": 82,
    "energyEfficiencyRatingPotential": 90,
    "environmentalImpactRatingCurrent": 86,
    "environmentalImpactRatingPotential": 92,
    "autoGenerateKid": false,
    "transferOfFreehold": null,
    "kid": [
    {
        "url": "https://yourserver.com/pdfs/4534/sample.pdf",
        "caption": "Important document"
    }
    ],
    "fullMarketPrice": 230000,
    "depositPercentage": 5,
    "minSharePercentage": 45,
    "maxSharePercentage": 75,
    "subsidisedRent": 431.25,
    "subsidisedAsYearlyPercent": false,
    "monthlyServiceCharge": 108.9,
    "annualGroundRent": null,
    "reservationFee": null,
    "administrationFee": null,
    "estateCharge": 30,
    "buildingsInsurance": 15,
    "managementFee": 20,
    "reserveFundPayment": null,
    "monthlyRent": null,
    "rentalDeposit": null,
    "minTenancyMonths": null,
    "maxTenancyMonths": null,
    "fullSpecification": "<p><strong>GENERAL</strong></p><ul><li>Open plan layout</li><li>Cool and contemporary interior</li><li>Ample storage throughout</li><li>Welcoming and modern communal areas</li><li>Bold outdoor spaces</li></ul><p><strong>KITCHEN</strong></p><ul><li>Ample workspaces</li><li>Fridge/freezer</li><li>Washer/dryer</li><li>Dishwasher</li><li>Separate electric oven and gas hob plus extractor fans</li></ul>",
    "fullCircleId": 45392,
}

# Archive an independent unit

To archive an independent units issue a:

PATCH to /api/rest/open/independent-units/{property.id}/archive

where {property.id} is the Id in KPro Marketing of the independent unit to archive. Once an independent unit is archived it cannot be restored.

# Additional information

# Label conventions

Possible values for some fields need to match available values in KPro Marketing. Find below KPro Marketing label convention for those fields.

# Scheme groups

For sale

Label	Description
shared-ownership	Scheme that allows buyers to own a share and then rent the part they do not own at a reduced rate. Display value: Shared ownership.
help-to-buy	Scheme that offers an equity loan where the government lends money to buy a newly-built home. Display value: Help to Buy only.
first-dibs	Scheme to ensure that new, lower-cost homes in the capital are marketed and sold exclusively to Londoners and UK-based buyers first. Display value: First Dibs only.
help-to-buy-and-first-dibs	Combine two previous schemes. Display value: Help to Buy & First Dibs.
discounted-market-sale	Low-cost home ownership product where a housing provider offers a discount on the purchase of a new build property. Display value: Discounted market sale.
private-sale	The option to use when you want to sale a property in the private market. Display value: Private sale.

To rent

Label	Description
london-living-rent	Scheme for middle-income households who now rent and want to build up savings to buy a home. Display value: London living rent.
discount-market-rent	Offers home seekers the opportunity to rent a home at a rent that is 20% less than the market rate. It is also sometimes known as Intermediate Rent. Display value: Discounted market rent.
rent-to-buy	Scheme that allows you to rent a property for less than the market price for a set amount of time, in which you are expected to use the money saved from the lower rent for a deposit to buy the property after the tenancy ends. Display value: Rent to Buy (Outside London).
private-rent	The option to use when you want to rent a property in the private market. Display value: Private rent.

# Shared ownership types

Only applicable for shared ownership properties. It's an integer value as defined in the following table:

Value	Description
1	AHP 2021 to 2026 - Standard shared ownership
2	AHP 2021 to 2026 - Designated Protected Area restricted staircasing to 80%
3	AHP 2021 to 2026 - Designated Protected Area mandatory buyback to 100%
4	AHP 2021 to 2026 - Older Persons Shared Ownership
5	AHP 2021 to 2026 - Home Ownership for people with long term disabilities
6	SOAHP 2016 to 2021 - Standard shared ownership
7	SOAHP 2016 to 2021 - Designated Protected Area restricted staircasing to 80%
8	SOAHP 2016 to 2021 - Designated Protected Area mandatory buyback to 100%
9	SOAHP 2016 to 2021 - Older Persons Shared Ownership

# Availability status

The labels are the same regardless if the property is for sale or to rent, but the meaning depends on the purpose.

For sale

Label	Description
coming-soon	The property is listed for sale soon. Display value: Coming soon.
available	The property is available for sale. Display value: For sale.
under-offer	The property is currently under offer. Display value: Sale Under offer.
closed	The property was sold. Display value: Sold.

To rent

Label	Description
coming-soon	The property is listed to rent soon. Display value: Coming soon.
available	The property is available to rent. Display value: To rent.
under-offer	The property is currently under offer. Display value: Rent under offer.
closed	The property is currently rented. Display value: Rented.

# Property types

Property types (or building types) fields to describe the kind of property for sale or to rent.

Label	Description
flat	Flats are mostly single-level residential properties comprising of a set or rooms all located on one floor. Display value: Flat.
semi-detached-house	Property attached to just one neighbouring house as part of a block of just two houses. Display value: Semi-detached house.
detached-house	A stand-alone residential structure that does not share outside walls with another house or building. Display value: Detached house.
terraced-house	One of a row of similar houses joined together by their side walls. Display value: Terraced house.
end-of-terrace-house	A house attached to just one neighbour that in its turn is attached to two neighbours. Display value: End of terrace house.
bungalow	Single-storey detached house or has a second storey built into a sloping roof. Display value: Bungalow.
maisonette	A set of rooms for living in typically on two storeys as part of a larger building with a separate entrance from rest of the building. Display value: Maisonette.
studio	A single room with cooking facilities which has its own bathroom attached. Display value: Studio.
house	The default value to use when the house is not in any of the previous categories. Display value: House.

# Property features

Features are grouped in different categories, although these categories are just for organizational purposes. When defining features, just add all applicable, and separate them by comma.

Parking

Label	Description
off-street-parking	Whether the property has Off street parking facility available.
on-street-parking	Whether On street/resident parking facility is available.
underground-parking	Whether the property has Underground parking facility available.
driveway	Whether the property has Driveway parking facility available.
single-garage	Whether Single garage parking facility is available.
double-garage	Whether Double garage parking facility is available.

Outside space: What outside areas are available.

Label	Description
back-garden	The property has access to a back garden area.
communal-garden	The property has access to a communal garden.
enclosed-garden	Whether enclosed garden outside area is available.
front-garden	Whether the front garden outside area is available.
private-garden	Whether the property has a private garden.
rear-garden	Whether the property has a rear garden.
terrace	Whether the property has a terrace.
patio	Whether the property has a patio.

Others

Label	Description
wheelchair-accessible	Whether the property is wheelchair accessible.
pets-allowed	Whether it is allowed to have pets.
central-heating	Whether the property has central heating.
double-glazing	Whether the property has double glazed windows.
lift-access	Whether the property has lift access.

# Furniture status labels

furnished
part-furnished
unfurnished

# Floor labels

Floor in which the entrance of the property is located. The layout of floors within a multi-storey building is defined as follows:

Label	Description
ground	The entrance floor of the property is on the ground floor.
1	The entrance floor of the property is on the 1st floor.
2	The entrance floor of the property is on the 2nd floor.
3	The entrance floor of the property is on the 3rd floor.
4	The entrance floor of the property is on the 4th floor.
5	The entrance floor of the property is on the 5th floor.
6	The entrance floor of the property is on the 6th floor.
7	The entrance floor of the property is on the 7th floor.
8	The entrance floor of the property is on the 8th floor.
9	The entrance floor of the property is on the 9th floor.
10+	The entrance floor of the property is higher than the 9th floor.
lower	The entrance floor of the property is on the lower ground.
basement	The entrance floor of the property is on the basement.

# Freehold transfer options

Transfer of freehold statement options. Find the value on the column id to check the meaning.

Id	Description
1	At 100% ownership, the freehold will transfer to you.
2	At 100% ownership, the freehold will not transfer to you because.
3	At 100% ownership, the leasehold title remains in your name but your shared ownership obligations fall away.

# Understanding prices fields

Although property payloads contains all available price fields, their use depends on the occupancy type and the schemes.

Warning

Some or even all the relevant price fields could be null. In those cases those values should be treated as TBA (To be announced).

There are two different occupancy types: For sale or To rent. The listing and property details always contain the field forSale, which will be true when the occupancy type is For sale, otherwise is To rent. This is a computed field, obtained from the schemeGroup.

# For sale fields

There are basically three different cases for sale properties, regarding the price fields:

Standard: There is a fullMarketPrice, and to buy the property, it is necessary to pay a depositValue.
Shared ownership: There is a share to buy and the rest to rent. The minimum share to buy is returned in the field minSharePercentage and the amount (computed from the full market price) is returned in minShareValue. The monthly rent for the rest is returned in the field subsidisedMonthlyRent. The depositValue is usually lower, because it's computed against the price for the share to buy.
The buyer can receive a government loan: It behaves like the Standard case, but field maxGovernmentLoanPercent will contain the percent of the government loan (usually 20 or 40, depending if the property is in London or not), and maxGovernmentLoanValue the amount it represents out of the fullMarketPrice.

When it has the behavior of Shared ownership, the flag isSharedOwnership will be true.

When buyers could receive a government loan, and fullMarketPrice is null, maxGovernmentLoanValue will be also null.

There are other fields that do not depend on the schemes, like:

monthlyServiceCharge: Monthly bill that covers the costs of any repairs or maintenance to the structure of the building, including drainage, insurance and management charges.
annualGroundRent: Rent to pay annually to the freeholder or landlord of the leasehold property. Notice this field only make sense when tenure is leasehold.
reservationFee: Reservation fee to a developer that allows a buyer to reserve a property for a period.
administrationFee: Fee charged by an agency to cover expenses related to record-keeping and/or other.

# To rent fields

There is no different cases for properties to rent.

The most important value is monthlyRent, but sometimes is a good idea to display the weeklyRent too, which is a computed value. rentalDeposit, minTenancyMonths and maxTenancyMonths are sometimes specified by the housing providers, although it is not common.

administrationFee is the other relevant field for properties to rent.

← Leads API Listings API →