# GET properties

Get information about the matched properties including the associated titles and parcels.
You may provide only one of the three identifiers - an address, Council Property Number (CPN) in combination with Municipality or Property Persistent Feature Identifier (PFI).
This helps to confirm the right title and/or property before then making an order for available certificates.

Endpoint: GET /discovery/v1/properties
Version: 1.9.0
Security: oauthClientCredentials

## Query parameters:

  - `propertyPfi` (string)
    Property Persistent Feature Identifier (PFI) which uniquely identifies a property. A PFI is generated by the state once for each property at the point of creation and remains constant until a property is retired.
Only a single property will be returned when this identifier is used.
This parameter cannot be used in conjunction with propertyNumber + municipalityName or eziAddress.
    Example: "208045633"

  - `propertyNumber` (string)
    Property Number assigned by the local government authority of the property. This parameter must always be paired with municipalityName. Also known as Council Property Number (CPN).
Only a single property will be returned when this identifier is used.
This parameter cannot be used in conjunction with propertyPfi or eziAddress.
    Example: "603787"

  - `municipalityName` (string)
    Municipality of the property. This parameter must always be paired with propertyNumber.
Only a single property will be returned when this identifier is used.
This parameter cannot be used in conjunction with propertyPfi or eziAddress.
    Example: "MELBOURNE"

  - `eziAddress` (string)
    Property address as a single string (not broken into fields). It is the concatenation of key address attribute fields to provide a unique address for data matching. Format - blg_unit_, house_, road_name/type/suffix, plus locality & postcode fields.
Multiple properties may be be returned when this identifier is used.
This parameter cannot be used in conjunction with propertyNumber + municipalityName or propertyPfi.
Note that a single property can have multiple addresses, e.g. 113 MEW LANE BAMAWM 3561 and 50 TWADDLE LANE BAMAWM 3561
An address can also be linked to multiple properties, such as BASEMENT 2 LONSDALE STREET MELBOURNE 3000.
As a result, this identifier should be considered less specific than propertyPfi.
    Example: "328/800 SWANSTON STREET CARLTON 3053"

  - `premium` (boolean)
    For customers who have premium access, specifies whether to include premium-only results in the discovery responses.
If set to true, premium information (such as unencrypted title IDs) will be included in the response.
Note that enabling this option may incur discovery charges.
    Example: true

## Header parameters:

  - `customer-id` (string)
    Identifier of the customer this request is on behalf of. For premium discovery requests only.
    Example: "12345"

  - `customer-reference` (string)
    Optional description to identify a transaction, used for billing purposes. Note that we'll be providing a separate order ID once the order has been submitted. For premium discovery requests only.
    Example: "customer-reference-001"

  - `idempotency-key` (string)
    Unique UUID used to prevent duplicate premium discovery orders. For premium discovery only.
This allows requests to be retried after a network failure without accidentally submitting two premium discovery orders.
If you receive a network error or timeout, you should resend the request with the same idempotency-key.
If the server is still processing the original POST, you will receive 429 Too Many Requests.
Idempotency keys expire after 24 hours.
    Example: "cc4d91e3-17af-4d11-b333-eb449e62ff07"

  - `x-correlation-id` (string)
    Optional unique UUID which can assist with tracing / debugging requests.
    Example: "824993ab-7366-4faa-963d-c456dec227a5"

## Response 200 fields (application/json):

  - `propertySummaries` (array, required)

  - `propertySummaries.propertyPfi` (string, required)
    Property persistent feature identifier (PFI) which uniquely identifies a property.
    Example: "208045633"

  - `propertySummaries.propertyStatus` (string, required)
    The status of a property identifies whether it is active or proposed.
Proposed properties are attached to proposed parcels. This is where a parcel sub-division has not yet been fully completed but has gone through a significant way through the approval stage and so recognised as proposed.
    Enum: "ACTIVE", "PROPOSED"

  - `propertySummaries.isCouncilPropertyRegistered` (boolean, required)
    This identifies whether the property has an associated Council Property Number (true) or not (false). There are properties which do not have a council property number and are typically common property areas of apartments and as such, cannot be bought or sold.
If false then the councilPropertyDetails section will be omitted
    Example: true

  - `propertySummaries.councilPropertyDetails` (object)

  - `propertySummaries.councilPropertyDetails.propertyNumber` (string)
    Property Number assigned by the local government authority of the property. Also known as Council Property Number (CPN).
    Example: "603787"

  - `propertySummaries.councilPropertyDetails.municipalityName` (string, required)
    Municipality of the property.
    Example: "MELBOURNE"

  - `propertySummaries.isMultiAssess` (boolean, required)
    If the property is known as Multi-assessment, then this is where more than one property belong to the same parcel. A typical example might be where individual shops belong in a shopping centre property.
    Example: true

  - `propertySummaries.propertyCreatedDate` (string, required)
    Date the property and its PFI was created by the state.
    Example: "2012-10-03 02:17:46"

  - `propertySummaries.primaryAddress` (object, required)

  - `propertySummaries.primaryAddress.eziAddress` (string, required)
    Property address as a single string (not broken into fields). It is the concatenation of key address attribute fields to provide a unique address for data matching. Format - blg_unit_, house_, road_name/type/suffix, plus locality & postcode fields.
    Example: "UNIT 328 LEVEL 3 800 SWANSTON STREET CARLTON VIC 3053"

  - `propertySummaries.primaryAddress.addressDetails` (object, required)

  - `propertySummaries.primaryAddress.addressDetails.buildingName` (string)
    Example: "COMPANYX MAIN MALL"

  - `propertySummaries.primaryAddress.addressDetails.unitType` (string)
    Example: "UNIT"

  - `propertySummaries.primaryAddress.addressDetails.unitNumber` (string)
    Example: "201A"

  - `propertySummaries.primaryAddress.addressDetails.levelType` (string)
    Example: "GROUND"

  - `propertySummaries.primaryAddress.addressDetails.levelNumber` (string)
    Example: "30-36"

  - `propertySummaries.primaryAddress.addressDetails.streetNumber` (string)
    Example: "30"

  - `propertySummaries.primaryAddress.addressDetails.streetName` (string)
    Example: "BOURKE"

  - `propertySummaries.primaryAddress.addressDetails.streetType` (string)
    Example: "STREET"

  - `propertySummaries.primaryAddress.addressDetails.streetSuffix` (string)
    Example: "MALL"

  - `propertySummaries.primaryAddress.addressDetails.suburbTownLocality` (string)
    Example: "MELBOURNE"

  - `propertySummaries.primaryAddress.addressDetails.postcode` (string)
    Example: "3000"

  - `propertySummaries.aliasAddresses` (array)
    List of alias addresses associated with the requested property. Note, if a property has no alias addresses, an empty array will be returned.

  - `propertySummaries.waterAuthorities` (object)

  - `propertySummaries.waterAuthorities.metroWaterAuthority` (string)
    The metro water authority.
    Example: "YARRA VALLEY WATER"

  - `propertySummaries.waterAuthorities.regionalWaterAuthority` (string)
    The regional water authority.
    Example: "SOUTHERN RURAL WATER"

  - `propertySummaries.waterAuthorities.ruralWaterAuthority` (string)
    The rural water authority.
    Example: "EAST GIPPSLAND WATER"

  - `propertySummaries.landParcels` (array, required)
    List of parcels associated with the requested property(s).
A parcel is generally a piece of physical land as defined by a geographic shape. It is also possible for a parcel to not be a physical piece of ground, but be defined also by where it is vertically.
Note, if no associated parcels are found, an empty array will be returned.

  - `propertySummaries.landParcels.spi` (string, required)
    A Standard Parcel Identifier (SPI) uniquely identifies a parcel. An SPI typically consists of either a Lot on Plan or a Crown Allotment.
A Lot on Plan defines the allocated lot number on a particular plan. For example '101\PS328573' is lot 101 on the plan of subdivision 328573.
There are instances of an SPI not containing a lot, eg: 'TP109554'.
A Crown Allotment parcel is defined by up to five different factors including Allotment, Block, Portion, Section and SubDivision.
For example '12~10A\PP5762' is Allotment 12 in Section 10a on the Parish Plan 5762.
    Example: "3A2\\PS515587"

  - `propertySummaries.landParcels.parcelType` (string)
    The parcel types determine what can be done with the parcel. The type can be a lot (a normal parcel of land), a unit (belonging to an apartment development), Common property (jointly owned land as defined by something such as a body corporate), roads or reserves.
    Enum: "COMMON_PROPERTY", "LOT", "RESERVE", "ROAD", "UNIT"

  - `propertySummaries.landParcels.lotType` (string)
    The lot type gives an indication of the use of the parcel or describes any lot limitations. Generally when the parcel has a parcel type of ‘lot’ or ‘unit’. They can be restricted (meaning it must be sold with another parcel), unrestricted (it does not need to be sold along with another parcel), an accessory unit like a storage area in an apartment complex or a carpark.
    Enum: "ACCESSORY_UNIT", "CARPARK", "RESTRICTED", "UNRESTRICTED"

  - `propertySummaries.landParcels.parcelStatus` (string)
    The status of a parcel identifies whether it is active or proposed.
This is where a parcel sub-division has not yet been fully completed but has gone through a significant way through the approval stage and so recognised as proposed.
    Enum: "ACTIVE", "PROPOSED"

  - `propertySummaries.landParcels.lot` (string)
    Example: "3A2"

  - `propertySummaries.landParcels.planNumber` (string)
    Example: "PS515587S"

  - `propertySummaries.landParcels.parish` (string)
    Parish name.
    Example: "YEO"

  - `propertySummaries.landParcels.township` (string)
    Township name.
    Example: "BARWON DOWNS TP"

  - `propertySummaries.landParcels.allotment` (string)
    Crown Allotment.
Crown Allotment descriptor.
    Example: "15D"

  - `propertySummaries.landParcels.block` (string)
    Crown Block.
A part of the parcel descriptor. It is utilized in combination with either Lot and Plan number or Allotment and Parish code.
    Example: "1"

  - `propertySummaries.landParcels.section` (string)
    Section.
A part of the parcel descriptor. It is utilized in combination with either Lot and Plan number or Allotment and Parish code.
    Example: "A"

  - `propertySummaries.landParcels.portion` (string)
    Crown Portion.
Crown Portion descriptor.
    Example: "105"

  - `propertySummaries.landParcels.subdivision` (string)
    Crown Subdivision.
Crown Subdivision descriptor.
    Example: "16"

  - `propertySummaries.titles` (array, required)
    List of titles associated with the requested property(s). Note, if no associated titles are found, an empty array will be returned.

  - `propertySummaries.titles.titleId` (string, required)
    An encrypted title identifier. Access to Vol/Fol is available only for premium discovery due to associated charges.
This value is not guaranteed to remain stable over time. Customers should avoid relying on its persistence or consistency across API calls or over extended periods.
    Example: "qp0gjuieZ5VzbNKtT/eZvqPryobRkEYxMA=="

  - `propertySummaries.titles.volumeFolio` (string)
    For premium discovery responses, this field contains the Volume/Folio (Vol/Fol) of a title.
    Example: "10940/843"

  - `propertySummaries.titles.titleStatus` (string, required)
    The status of the title informs whether it is currently active, has become cancelled or partially cancelled.
    Enum: "ACTIVE", "CANCELLED", "PARTIALLY_CANCELLED"

  - `propertySummaries.titles.titleType` (string, required)
    Describes the ownership type of the title, the main two being Freehold for property owned by individuals and companies, and Crown land which is administered by public authorities.
    Enum: "ALPINE_LEASE", "CITY_LINK_LEASE", "CROWN_GRANT", "CROWN_LAND", "CROWN_LEASE", "FREEHOLD", "IDENTIFIED", "MINERAL_EXCLUDES", "MINERAL_INCLUDES", "TREASURERS_RECEIPT"

  - `orderSummary` (object)

  - `orderSummary.orderId` (string, required)
    Unique number to identify an order.
    Example: "10219435"

  - `orderSummary.totalPrice` (integer, required)
    The total price (in cents) for this order (including gst).
    Example: 891

  - `orderSummary.totalGst` (integer, required)
    The total GST amount (in cents) for this order.
    Example: 89

## Response 400 fields (application/json):

  - `errorType` (string)
    Stable error code that can be used to decide how to hand an error.
    Example: "UNAUTHORIZED"

  - `errorMessage` (string)
    Invalid Authorization token.

## Response 401 fields (application/json):

  - `errorType` (string)
    Stable error code that can be used to decide how to hand an error.
    Example: "UNAUTHORIZED"

  - `errorMessage` (string)
    Invalid Authorization token.

## Response 403 fields (application/json):

  - `errorType` (string)
    Stable error code that can be used to decide how to hand an error.
    Example: "UNAUTHORIZED"

  - `errorMessage` (string)
    Invalid Authorization token.

## Response 404 fields (application/json):

  - `errorType` (string)
    Stable error code that can be used to decide how to hand an error.
    Example: "UNAUTHORIZED"

  - `errorMessage` (string)
    Invalid Authorization token.

## Response 429 fields (application/json):

  - `errorType` (string)
    Stable error code that can be used to decide how to hand an error.
    Example: "UNAUTHORIZED"

  - `errorMessage` (string)
    Invalid Authorization token.

## Response 500 fields (application/json):

  - `errorType` (string)
    Stable error code that can be used to decide how to hand an error.
    Example: "UNAUTHORIZED"

  - `errorMessage` (string)
    Invalid Authorization token.