# Proprietor Search

Examples of how to use the proprietor search API to find proprietors and their titles.

A combination of Get Individual / Company Proprietor Names and Get Proprietors endpoints can be used to find proprietors and their associated titles.

## API Endpoints Summary

| Endpoint | Purpose | Key Parameters | Returns | Pagination |
|  --- | --- | --- | --- | --- |
| `GET /discovery/v2/proprietors` | Search for proprietors and their associated titles | `lastName`, `givenName`, `companyName`, `pageNumber` | List of proprietor summaries with title details | Yes (200 per page) |
| `GET /discovery/v2/proprietor-names/individual` | Find individual proprietor names using tiered search | `lastName`, `givenName` | List of matching individual proprietor names | No (max 100) |
| `GET /discovery/v2/proprietor-names/company` | Find company proprietor names using tiered search | `companyName` | List of matching company names | No (max 100) |


## Common Workflows

### Discover Individual Proprietors and Their Titles

Use this two-step workflow to search for individual proprietors:

1. **Find proprietor names** - Use the individual proprietor names endpoint to find matching names using `lastName` and/or `givenName` → [See Section 2](#2-get-individual-proprietor-names)
2. **Get title details** - Use the `lastName` and `givenName` from the results to search the proprietors endpoint for associated title information → [See Section 1](#1-get-proprietors)


### Discover Company Proprietors and Their Titles

Use this two-step workflow to search for company proprietors:

1. **Find company names** - Use the company proprietor names endpoint to find matching companies using `companyName` → [See Section 3](#3-get-company-proprietor-names)
2. **Get title details** - Use the `companyName` from the results to search the proprietors endpoint for associated title information → [See Section 1](#1-get-proprietors)


### Company-Like Names in Unordered Category

Some proprietor names may **look like company names** (e.g., "F.B. & W.L. O'CONNOR PTY. LTD.") but are actually stored in the **Unordered** category. Therefore, these names should be searched using the `GET /ddp/discovery/v2/proprietor-names/individual` endpoint with the `lastName` parameter, rather than the company names endpoint. Unordered proprietors are those that have no given name but also have not been cateogorised into the company types.

**To search for these:**

- See the example in [Section 2c](#2c-last-name-only-search) which demonstrates this with "F.B. & W.L. O'CONNOR PTY. LTD." appearing in the `lastName` field.


**Note:** All the proprietor search APIs perform a **case-insensitive** search on all names.

## 1. GET proprietors

Searches for active property owners (proprietors) by:

- Last name with or without given name
- Company name


### Query Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| lastName | string | Conditional | The last name of the proprietor to search for. |
| givenName | string | Optional | The given name(s) of the proprietor to search for. |
| companyName | string | Conditional | The company name of the proprietor to search for. |
| pageNumber | integer | Optional | The page number for paginated results (default: 1). |
| premium | boolean | Optional | Whether the decrypted title IDs (volume folios) are shown. Defaults to False if not provided. |


#### Validation Rules

- At least one of the following must be provided:
  - `lastName` (with or without `givenName`), or
  - `companyName`
- `companyName` and `lastName` are **mutually exclusive**
- Names cannot be only numbers or numbers with commas/periods (e.g., "123" or "1,234.56")
- Names cannot start or end with hyphens or apostrophes (e.g., "-Smith" or "Jones'")


### Proprietor Types

| Proprietor Type | Description |
|  --- | --- |
| Ordered/Individual | Ordered proprietors refer to individuals with at least one given name and a last name. |
| Unordered | Unordered proprietors refer to proprietors with just a last name. [Note that they may or may not be individuals](#company-like-names-in-unordered-category). |
| Company/Government/Other | These three types always refer to organisation proprietors rather than individuals. |


#### Parameter Mapping to Proprietor Types

The query parameters are mapped to proprietor types as follows:

| Parameters | Search Category | Proprietor Types Searched |
|  --- | --- | --- |
| `lastName` + `givenName` | Individual Search | Ordered/Individual |
| `lastName` only | Individual Search | Unordered |
| `companyName` | Company Search | Company, Government and Other |


### Response Details

The API returns a list of property ownership records from VOTS (Victorian On-line Title System) that match the search criteria, including details about associated titles.

The search filters results based on:

- Active proprietors
- Non-barred titles
- Proprietor type matching search criteria (Individual/Ordered, Company, or Unordered)
- The results are paginated with a **default page size of 200** records per page.


#### Premium response

If `premium` query parameter is set to `True` then the decrypted volume folios are shown alongside the encrypted title IDs. The decrypted values are shown in a separate field called `volumeFolio`. Premium requests incur a charge so an additional `orderSummary` field is added to the response which contains details of the Land Index Surcharge order submitted to LANDATA.

Note that each request will incur a charge so each page of results will have a new charge. Therefore you are able to get a maximum of 200 proprietor details and their decrypted volume folios in a single request.

### 1a. GET proprietors with lastName only

- If `lastName` only is provided, the search will perform an "exact" and **case-insensitive** search Unordered proprietors where the name matches the `lastName` value. Without a given name, you will only get proprietors without a given name. For example, if you provide `lastName` = "SMITH", you will not get any individual proprietors such as JOHN SMITH, JANE SMITH etc. If there are any unordered proprietors where the name is just SMITH and there is no given name, then those will be returned. If you don't know the given name and want to search for individuals with any given name and a specific last name use the [individual proprietor-names endpoint instead](#2c-last-name-only-search).


### Example request

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v2/proprietors?lastName=O%27CONNOR' \
--header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

### Example response

```json
{
  "proprietorSummaries": [
    {
      "lastName": "O'CONNOR",
      "titleDetails": {
        "titleId": "xxx",
        "titleStatus": "ACTIVE",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 3A2 on Plan of Subdivision 515587S.",
        "municipality": "MARIBYRNONG"
      }
    },
    {
      "lastName": "O'CONNOR",
      "titleDetails": {
        "titleId": "xxx",
        "titleStatus": "ACTIVE",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 2B2 on Plan of Subdivision 615587S.",
        "municipality": "KNOX"
      }
    },
    {
      "lastName": "O'CONNOR",
      "titleDetails": {
        "titleId": "xxx",
        "titleStatus": "CANCELLED",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 1C2 on Plan of Subdivision 715587S.",
        "municipality": "MELTON"
      }
    }
    // ... more entries omitted for brevity ...
  ],
  "pagination": {
    "pageSize": 200,
    "nextPage": 2
  }
}
```

The response is paginated and will return a maximum of 200 proprietor summaries per page. If there are more results, a `nextPage` field will be included in the `pagination` object indicating the next page number to retrieve the next set of results.

#### Example request for page 2:

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v2/proprietors?pageNumber=2&lastName=O%27Connor' \
--header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

The last page will not include a `nextPage` field in the pagination object, indicating there are no more results to retrieve.

### 1b. GET proprietors with lastName and givenName

- When both names are supplied, the endpoint searches for Ordered proprietors.
- There can be multiple given names separated by a space (e.g., "Brian James").


#### Example request

Searching for proprietors with `lastName` "O'CONNOR" and `givenName` "BRIAN" will perform an **exact** and **case-insensitive** search on `lastName` equals "O'CONNOR" and `givenName` equals "BRIAN".

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v2/proprietors?givenName=Brian&lastName=O%27Connor' \
--header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

#### Example response

```json
{
  "proprietorSummaries": [
    {
      "lastName": "O'CONNOR",
      "givenName": "BRIAN",
      "titleDetails": {
        "titleId": "J7e/ppV5DvdYFtgo5WMJGRuf1P5oCg2Jug==",
        "titleStatus": "CANCELLED",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 1 of Plan PS406245G",
        "municipality": "GLENELG"
      }
    },
    {
      "lastName": "O'CONNOR",
      "givenName": "BRIAN JAMES",
      "titleDetails": {
        "titleId": "Mt5j6nmKjmAA37CS/Jyf+OpSOeRgcSa43Q==",
        "titleStatus": "ACTIVE",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 4 of Plan PS527923L",
        "municipality": "CARDINIA"
      }
    },
    {
      "lastName": "O'CONNOR",
      "givenName": "BRIAN LOUISE",
      "titleDetails": {
        "titleId": "xxxx",
        "titleStatus": "ACTIVE",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 2 of Plan SP033474P",
        "municipality": "WODONGA"
      }
    },
    {
      "lastName": "O'CONNOR",
      "givenName": "BRIAN MAY",
      "titleDetails": {
        "titleId": "xxxx",
        "titleStatus": "ACTIVE",
        "titleType": "FREEHOLD",
        "landDescriptionText": "CA 1 Section 2 Township of Glenorchy Parish of Glenorchy",
        "municipality": "NORTHERN GRAMPIANS"
      }
    },
    {
      "lastName": "O'CONNOR",
      "givenName": "BRIAN MCKENZIE",
      "titleDetails": {
        "titleId": "xxxx",
        "titleStatus": "CANCELLED",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 2 of Plan SP021936T",
        "municipality": "MONASH"
      }
    }
    // ... more proprietor summaries
  ],
  "pagination": {
    "pageSize": 27
  }
}
```

### 1c. GET proprietors with companyName

Searches for company proprietors when `companyName` is provided:

- Searches for Company and Unordered proprietors.
- Performs an **exact** and **case-insensitive** search on `companyName`


#### Example request

Searching for proprietors with `companyName` "Danaher" will perform an "exact" and **case-insensitive** search for proprietors with `companyName` "Danaher".

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v2/proprietors?companyName=Danaher' \
--header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

#### Example response

```json
{
  "proprietorSummaries": [
    {
      "companyName": "DANAHER",
      "titleDetails": {
        "titleId": "xxxx",
        "titleStatus": "ACTIVE",
        "titleType": "FREEHOLD",
        "landDescriptionText": "Lot 2 of Plan PS825134D",
        "municipality": "LATROBE"
      }
    }
  ],
  "pagination": {
    "pageSize": 1
  }
}
```

## 2. GET individual proprietor names

Retrieves individual proprietor names by `lastName` and/or `givenName` using a tiered search strategy that progressively matches results across three levels:

1. **Exact matches** - exact matching first (highest priority)
2. **Prefix matches** - name startswith search (medium priority)
3. **Partial matches** - wildcard matching (contains or LIKE) (lowest priority)


- The result set is ordered by relevance based on the match type (exact > prefix > partial) and then alphabetically by `lastName` and/or `givenName`.
- Limited to 100 results and not paginated.


### Query Params:

At least one of the following query parameters must be provided:

| Parameter | Type | Description |
|  --- | --- | --- |
| lastName | string | The last name of the proprietor to search for. |
| givenName | string | The given name of the proprietor to search for. |


- This endpoint will search for both Ordered/Individual and Unordered proprietors


### 2a. Search with lastName and givenName

Search for individual proprietors with `givenName` "John" and `lastName` "O'Conn", limit results to 100 and order by relevance (exact > prefix > partial) and then alphabetically by `lastName` and `givenName`.

#### Example requests

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v2/proprietor-names/individual?lastName=O%27Conn&givenName=John' \
--header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

#### Example response

```json
{
  "proprietorNames": [
    {
      "lastName": "O'CONNELL",
      "givenName": "JOHN"
    },
    {
      "lastName": "O'CONNELL",
      "givenName": "JOHN ALAN"
    },
    {
      "lastName": "O'CONNELL",
      "givenName": "JOHN JAN RICHARD"
    },
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": "LAURENCE JOHN"
    },
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": "MARK DUNSTAN JOHN"
    },
    {
      "lastName": "O'CONNELL",
      "givenName": "BRIAN JOHN WILLIAM"
    }
    // ... more proprietor names(truncated for brevity) ...
  ]
}
```

### 2b. Given Name Only Search

Search for individual proprietors with `givenName` "CARMEL" and any last name, limit results to 100 and order by relevance (exact > prefix > partial) and then alphabetically by `lastName` and `givenName`.

##### Request

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v2/proprietor-names/individual?givenName=CARMEL' \
  --header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
  --header 'Accept: application/json' \
  --header 'Authorization: ••••••'
```

##### Response

```json
{
  "proprietorNames": [
    {
      "lastName": "ABBOTT",
      "givenName": "CARMEL"
    },
    {
      "lastName": "ABBOUD",
      "givenName": "CARMEL"
    },
    {
      "lastName": "BARKER",
      "givenName": "CARMEL"
    },
    {
      "lastName": "BARNES",
      "givenName": "CARMEL"
    },
    {
      "lastName": "ABBOTT",
      "givenName": "CARMELA ELAINE BRODRICK"
    },
    {
      "lastName": "BARKER",
      "givenName": "CARMEL"
    },
    {
      "lastName": "ACOCKS",
      "givenName": "CARMEL THOMAS"
    }
    // ... more proprietor names(truncated for brevity) ...
  ]
}
```

### 2c. Last Name Only Search

Search for individual proprietors with `lastName` and any given name

Note, [some names look like companies but are actually in the unordered category](#company-like-names-in-unordered-category) and therefore need be searched using the individual endpoint + last name.

#### Example request

```bash
curl --location 'https://dev.api.servictoria.io/ddp/discovery/v2/proprietor-names/individual?lastName=O%27CONNOR%20PTY.%20LTD' \
--header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

#### Example response

```json
{
  "proprietorNames": [
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": ""
    },
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": "ALAN JAMES RITCHIE"
    },
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": "ALLAN JEAN"
    },
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": "ASSUNTA RONALD"
    },
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": "BEVERLEY PHILIP"
    },
    {
      "lastName": "F.B. & W.L. O'CONNOR PTY. LTD.",
      "givenName": "CARMEL RITA ALICE"
    }
    // ... more proprietor names(truncated for brevity) ...
  ]
}
```

## 3. GET company proprietor names

Discover company proprietor names using tiered search (similar to individual proprietor search) that progressively matches results across three levels:

1. **Exact matches** - exact matching first (highest priority)
2. **Prefix matches** - name startswith search (medium priority)
3. **Partial matches** - wildcard matching (contains or LIKE) (lowest priority)


### Query Params:

| Parameter | Type | Description |
|  --- | --- | --- |
| companyName | string | The company name to search for. |


- This endpoint searches for Company / Government / Other proprietors that don't fit into Ordered or Unordered categories.
- The result set is ordered by relevance based on the match type (exact > prefix > partial) and then alphabetically by company name.
- Search response is limited to 100 results and is **not** paginated.


#### Example request

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v2/proprietor-names/company?companyName=AUSTRALIA' \
--header 'x-correlation-id: 824993ab-7366-4faa-963d-c456dec227a5' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'
```

#### Example response

```json
{
  "proprietorNames": [
    {
      "companyName": "AUSTRALIA AND NEW ZEALAND BANKING GROUP LTD"
    },
    {
      "companyName": "AUSTRALIAN AFFORESTATION PTY LTD"
    },
    {
      "companyName": "AMES AUSTRALIA"
    }
  ]
}
```