# Property Detail

`GET /property_detail`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/property_detail`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/property_detail`

The property detail query is designed to provide the resident and contact details (phone and email) linked to
an address referenced by a GNAF ID in the Global Data universe.

The query will automatically perform a connectivity check on any phone numbers and email addresses linked to
the resident. A DNC (Do Not Call) register check will also be performed and the results returned with the
response.

The connectivity and DNC checks can take some time to complete and this would cause the query to block until
the results are available. By providing the optional timeout parameter, the query will return at the end of the
timeout even if the phone and email checks have not yet completed. The query can then be retried at no cost by
providing the original api_reference.

| Service	                             | Typical response time | Maximum response time
:--------------------------------------|:----------------------|:---------------------
Address resolution and resident lookup | < 100mS	             | < 1 second
Phone connectivity check               | < 1 second            | 25 seconds (for some older land line exchanges)
Phone DNC check                        | < 2 seconds           | 10 seconds
Email deliverability check             | < 3 seconds           | 25 seconds

After the initial address and resident lookup, all phone and email checks are performed in parallel, so the
total blocking time is dependent on the slowest response.

## Polling for updates

Using a polling methodology allows for an improved user experience whereby the initial query can return quickly
with the resident data, and the application can then poll for completion of the email and phone checks.

If the api_reference is provided then the API will use the data from the previous request and wait for any
uncompleted checks to finish. The design purpose of this is to allow a shorter timeout to be set in the initial
query which will return the basic resident data and then poll for completion of the phone and email checks.

## An example use case:

```
$data = Http::get("https://gdapi.globaldata.net.au/api/v2/property_detail?" .
    "api_key={$api_key}&" .
    "gnaf_id={$gnaf_id}"
)->object();

// Render completed output to UI
...

while (! $data->complete) {
    $data = Http::get("https://gdapi.globaldata.net.au/api/v2/property_detail?" .
        "api_key={$api_key}&" .
        "gnaf_id={$gnaf_id}&" .
        "api_reference={$data->api_reference}"
    )->object();

    // Push update to UI
    ...
}
````

## Sandbox environment

When simulating queries in the sandbox environment the system will use a reduced sample dataset.
The following GNAF IDs will return resident and contact details (other sample addresses may return
the address only with no records):

| GNAF ID        | Address        | Suburb        | State | Postcode |
|:---------------|:---------------|:--------------|:------|:---------|
| GANSW716615055 | 35 YARALLA ST  | CONCORD WEST  | NSW   | 2138     |
| GANSW712900961 | 22 BRABYN ST   | WINDSOR       | NSW   | 2756     |
| GAVIC421647320 | 20 HARDY ST    | LILYDALE      | VIC   | 3140     |
| GAVIC419608268 | 8 WALTHAM ST   | RICHMOND      | VIC   | 3121     |

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `gnaf_id` | query | string | **Required.** The address GNAF ID. This is equivalent to the address_detail_pid on the GNAF table |
| `api_reference` | query | string (uuid) | The api_reference returned from a previous API request. Used to poll for updates to the result. |
| `timeout` | query | integer [1..120] | The maximum number of seconds to wait for phone and email checks to complete. If results are not completed before this timeout then the result will be returned with 'complete set to false, which indicates that one or more of the connectivity_status, dnc_status or deliverability_status are still 'processing'. Default: `20` |

## Responses

### 200 Result of property detail

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `complete` | boolean | Indicates if the phone and email checks have completed. If this is false then the connectivity_status, dnc_status and deliverability_status will be set to 'processing'. Example: `true` |
| `api_reference` | string (uuid) | A unique identifier for this request, used to get an update for the result at a later time Example: `738d9a89-b6fe-4fc1-96be-1389b2a506a2` |
| `total_records_available` | integer | Number of records in the result set Example: `1` |
| `address` | object | The address details for GNAF ID |
| `address.address_id` | string | The GNAF address id of the address Example: `GANSW716615055` |
| `address.address` | string | The combined street address as one string. Example: `35 YARALLA ST` |
| `address.suburb` | string | The matched suburb Example: `CONCORD WEST` |
| `address.postcode` | string | The matched postcode Example: `2138` |
| `address.state` | string | The matched state Example: `NSW` |
| `records` | array of objects | Resident records for this address |
| `records[].name_title` | string | Title of matched person or blank if unknown Example: `Ms` |
| `records[].name_first` | string | First name or Initial of matched person or blank if unknown Example: `MARY` |
| `records[].name_middle` | string | Middle name or Initial of matched person or blank if unknown Example: `SALLY` |
| `records[].name_last` | string | Last name of matched person Example: `JONES` |
| `records[].deceased` | string | Indicates if the person is deceased Enum: `Y`, `N` Example: `N` |
| `records[].gender` | string | Gender of the person or blank if unknown Enum: `M`, `F`, `X` |
| `records[].date_last_seen` | string (date) | Date the person was last seen at this address or blank if unknown Example: `2019-01-01` |
| `records[].phones` | array of objects | Phone numbers associated with matched person |
| `records[].phones[].phone` | string | Phone number in 0NSN format eg 0491570006 Example: `0299995000` |
| `records[].phones[].connectivity_status` | string | The status of the connectivity check for the phone * `processing` - The check is still in progress * `complete` - The check has completed and the connectivity_result is available * `error` - An error occurred during the check Enum: `processing`, `complete`, `error` Example: `complete` |
| `records[].phones[].connectivity_result` | string | The result of the connectivity check for the phone * `C` - The phone is connected * `D` - The phone is disconnected * `U` - The state of the phone number cannot be detected * `I` - The phone number is invalid Enum: `C`, `D`, `U`, `I` Example: `C` |
| `records[].phones[].dnc_status` | string | The status of the DNC check for the phone: * `processing` - The check is still in progress * `complete` - The check has completed and the dnc_result is available * `error` - An error occurred during the check Enum: `processing`, `complete`, `error` Example: `complete` |
| `records[].phones[].dnc_result` | string | The result of the DNC check for the phone: * `Y` - The phone number is on the DNC register * `N` - The phone number is not on the DNC register * `I` - The phone number is invalid Enum: `Y`, `N`, `I` Example: `N` |
| `records[].phones[].dnc_reference` | string | The DNC wash reference number returned by the DNC register Note: DNC results are valid for 30 days and must be rechecked after that time. Example: `123456789` |
| `records[].phones[].marketing_opt_in` | boolean | Indicates if the record is opted in to receive marketing * `true` - Record is opted in for marketing * `false` - Record is not opted in for marketing must not be contacted for any promotional or marketing purposes and is supplied for verification only Example: `true` |
| `records[].phones[].suppression` | string or null | Some records in the Global Data universe have been suppressed at the request of the record owner. If this field is present then the record has been suppressed. All other fields will be blank. |
| `records[].emails` | array of objects | Email addresses associated with matched person |
| `records[].emails[].email` | string | Email address Example: `mary_jones89@example.com` |
| `records[].emails[].deliverability_status` | string | The status of the deliverability check for the email * `processing` - The check is still in progress * `complete` - The check has completed and the deliverability_result is available * `error` - An error occurred during the check Enum: `processing`, `complete`, `error` Example: `complete` |
| `records[].emails[].deliverability_result` | string | The result of the deliverability check for the email * `Y` - The email address is deliverable * `N` - The email address is not deliverable * `U` - The email address cannot be checked * `I` - The email address is invalid * `E` - An error occurred during the check Enum: `Y`, `N`, `U`, `I`, `E` Example: `Y` |
| `records[].emails[].deliverability_ok_to_send` | string | Should email be sent to this address * `Y` - OK to send * `N` - Do not send * `U` - Unknown Some email addresses will report as deliverable (deliverability_result = 'Y') but not ok to send (deliverability_ok_to_send = 'N'). This can be because the address is a known spam trap or is enrolled in a global block list (serial complainer, etc).  Where possible information about this will be provided in the deliverability_detail field. Enum: `Y`, `N`, `U` Example: `N` |
| `records[].emails[].deliverability_detail` | string | Additional detail for the result if available Example: `Known spam trap` |
| `records[].emails[].marketing_opt_in` | boolean | Indicates if the record is opted in to receive marketing * `true` - Record is opted in for marketing * `false` - Record is not opted in for marketing must not be contacted for any promotional or marketing purposes and is supplied for verification only Example: `true` |
| `records[].emails[].suppression` | string or null | Some records in the Global Data universe have been suppressed at the request of the record owner. If this field is present then the record has been suppressed. All other fields will be blank. |

**Sample response**

```json
{
    "message": "Ok",
    "complete": true,
    "api_reference": "738d9a89-b6fe-4fc1-96be-1389b2a506a2",
    "total_records_available": 1,
    "address": {
        "address_id": "GANSW716615055",
        "address": "35 YARALLA ST",
        "suburb": "CONCORD WEST",
        "postcode": "2138",
        "state": "NSW"
    },
    "records": [
        {
            "name_title": "Ms",
            "name_first": "MARY",
            "name_middle": "SALLY",
            "name_last": "JONES",
            "deceased": "N",
            "gender": "M",
            "date_last_seen": "2019-01-01",
            "phones": [
                {
                    "phone": "0299995000",
                    "connectivity_status": "complete",
                    "connectivity_result": "C",
                    "dnc_status": "complete",
                    "dnc_result": "N",
                    "dnc_reference": "123456789",
                    "marketing_opt_in": true,
                    "suppression": "string"
                }
            ],
            "emails": [
                {
                    "email": "mary_jones89@example.com",
                    "deliverability_status": "complete",
                    "deliverability_result": "Y",
                    "deliverability_ok_to_send": "N",
                    "deliverability_detail": "Known spam trap",
                    "marketing_opt_in": true,
                    "suppression": "string"
                }
            ]
        }
    ]
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))