# GET parcels

Get information about the matched parcels including associated titles and properties. Provide a Standard Parcel Identifier (SPI).

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

## Query parameters:

  - `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.
If the input SPI contains a suffix character at the end and there is no matching parcel found, the suffix will be removed and the search retried.
Note: due the backslash (\) in SPI's it's important URL encoded this parameter, many HTTP clients will do this automatically.
    Example: "3A2\\PS515587"

  - `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):

  - `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"

  - `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"

  - `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"

  - `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"

  - `isPartParcel` (boolean)
    If true, only partial data available for this parcel

  - `parcelDetails` (object, required)

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

  - `parcelDetails.planNumber` (string)
    Example: "PS515587S"

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

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

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

  - `parcelDetails.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"

  - `parcelDetails.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"

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

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

  - `titles` (array)
    List of titles associated with the requested property(s).
If no associated titles are found an empty array will be returned.

  - `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=="

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

  - `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"

  - `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"

  - `properties` (array)

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

  - `properties.isMultiAssess` (boolean, required)
    Example: true

  - `properties.propertyStatus` (string, required)
    Status of the property.
    Enum: "ACTIVE", "PROPOSED"

  - `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.