Global Data
Browse endpoints
View as Markdown OpenAPI spec

Property Detail

GET /api/v2/property_detail operationId: property_detail

Live: https://gdapi.globaldata.net.au/api/v2/property_detail · Sandbox: 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

Query parameters

FieldDescription
gnaf_idrequired string

The address GNAF ID. This is equivalent to the address_detail_pid on the GNAF table
api_reference string (uuid)

The api_reference returned from a previous API request. Used to poll for updates to the result.
timeout 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

application/json
FieldDescription
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.
Standard error responses: 400 401 402 403 429 5XX See common error responses
Previous Address Lookup by Contact Next Real Estate Search