# 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/v1/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/v1/proprietor-names/individual` | Find individual proprietor names using tiered search | `lastName`, `givenName` | List of matching individual proprietor names | No (max 100) |
| `GET /discovery/v1/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/v1/proprietor-names/individual` endpoint with the `lastName` parameter, rather than the company names endpoint.

**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 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). |


#### 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'")


#### 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 | Ordered/Individual and Unordered |
| `companyName` | Company Search | Company, Government and Other |


### Response Details

The API returns a list of property ownership records from the VOTS (Victorian On-line Title System) database 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.


### 1a. GET proprietors with lastName only

- If `lastName` only is provided, the search will perform an "exact" and **case-insensitive** search for Ordered and Unordered proprietors with matching last name.
- For instance, searching for all proprietors with a `lastName` that matches "O'CONNOR" will search for an "exact" match for last name, but any given name.


### Example request

```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v1/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/v1/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` for "O'CONNOR"
- Perform a **contains** and **case-insensitive** search on `givenName` for "BRIAN"


> **Note:** The `givenName` parameter uses a "contains" search, meaning it will perform a wildcard match on any given name that includes the search term. For example, searching for "Brian" will return proprietors with given names such as "BRIAN", "BRIAN JAMES", "BRIAN LOUISE", etc.


```bash
curl --location 'https://test.api.servictoria.io/ddp/discovery/v1/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/v1/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/v1/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/v1/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 and therefore need be searched using the individual endpoint + last name.

#### Example request

```bash
curl --location 'https://dev.api.servictoria.io/ddp/discovery/v1/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/v1/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"
        }
    ]
}
```