Marketing Contact Lookup

POST /api/v2/marketing_contact_lookup operationId: marketing_contact_lookup

Live: https://gdapi.globaldata.net.au/api/v2/marketing_contact_lookup · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/marketing_contact_lookup

A focused contact lookup intended for marketing and outreach customers (for example real estate agents and marketing service providers). The caller supplies exactly one piece of information about a person and receives back up to max_records matching person records from our universe (default 1, max 25), each including name, contact details, the associated address and per-contact marketing opt-in status. Records are returned most-recent first.

Inputs

Exactly one of the following lookup keys must be supplied:

Key	Description
`phone`	Australian landline or mobile, in either `0NSN` (e.g. `0299995000`) or E.164 (`+61299995000`) format
`email`	Email address
`gnaf_id`	A GNAF address identifier (e.g. `GANSW716615055`)
`full_address`	A single free-text Australian address; this will be parsed and resolved to a GNAF
Address parts	`street_address` plus `postcode` (with optional `suburb` and `state` to improve match accuracy)

Plus the following optional parameters:

Key	Description
`max_records`	Integer, `1`-`25`, default `1`. The maximum number of person records to return in `records[]`. Persons are deduplicated by underlying identity before slicing, so a person who lived at the address across multiple tenancies counts as one record.
`require_marketing_optin`	Boolean, default `false`. When `true`, each returned record's phones and emails are filtered down to those explicitly opted in for marketing; persons left with no opted-in contacts are skipped entirely and we keep scanning further down the candidate list to fill the `max_records` quota.
`min_date_end`	ISO 8601 date (`YYYY-MM-DD`), optional. When supplied, candidate persons whose most-recent association ended before this date are excluded before the `max_records` slice. Inclusive at the boundary (a `date_end` equal to `min_date_end` passes). Persons with a current / open-ended association (`date_end: null` in the response) are always kept.

What we return

Up to max_records matching person records, ordered most-recent first, each containing name, date of birth (and DOB range, where the exact DOB is unknown), gender, all known phone numbers and email addresses (each annotated with a per-contact marketing_opt_in flag), and the associated address record.

Persons flagged as deceased are excluded. Records are filtered against our suppressions system. If no match is found (or all matches are excluded for the reasons above) the response returns an empty records: [] array.

What this query does NOT do

It does not perform a social check (use the Social Check API).
It does not perform a DNC check (use the DNC API).
It does not check phone or email connectivity / deliverability (use the Phone Ping and Email Ping APIs).
It does not return court data.
It does not return business associations.

Sandbox environment data

When simulating queries in the sandbox environment, the following records will return a match. The Marketing opt-in column shows which contacts are flagged as opted-in for marketing - use these to exercise both marketing_opt_in: true and marketing_opt_in: false in the response, and to test the require_marketing_optin: true filter behaviour.

First Name	Last Name	DOB	Address	Contact	Marketing opt-in
John	Smith	1998-03-21	20 HARDY ST, LILYDALE 3140 VIC	phone `0399999999`	no
John	Smith	1998-03-21		phone `0491222111`	no
John	Smith	1998-03-21		email `jsmith1998@example.com`	no
Robert	Brown	1971-03-18	8 WALTHAM ST, RICHMOND 3121 VIC	phone `0399998888`	yes
Mary	Jones	1989-08-12	35 YARALLA ST, CONCORD WEST 2138 NSW	phone `0299995000`	yes
Mary	Jones	1989-08-12		phone `0491999888`	no
Mary	Jones	1989-08-12		email `mary_jones89@example.com`	yes
Peter	Jones	1985-06-15	35 YARALLA ST, CONCORD WEST 2138 NSW	phone `0399994100`	yes
Peter	Jones	1985-06-15		phone `0491333222`	no
Peter	Jones	1985-06-15		email `peter_jones85@example.com`	yes
Emily	Tanner	1992-04-30	35 YARALLA ST, CONCORD WEST 2138 NSW (past)	phone `0399994201`	no
Emily	Tanner	1992-04-30		email `emily_tanner@example.com`	no
R	Brown	(unknown)	22 BRABYN ST, WINDSOR 2756 NSW	phone `0880885999`	no
R	Brown	(unknown)		email `rp_brown71@example.com`	no

Note that 35 YARALLA ST, CONCORD WEST 2138 NSW (GANSW716615055) is shared by three persons: Mary Jones and Peter Jones are current residents and Emily Tanner is a past resident. This makes it a useful sandbox fixture for exercising max_records and the require_marketing_optin scan-to-fill behaviour.

Worked examples:

{ "phone": "0299995000" } returns Mary Jones with two phones (one opt-in, one not) and one opt-in email.
{ "phone": "0299995000", "require_marketing_optin": true } returns Mary Jones with only her opt-in phone and her opt-in email.
{ "phone": "0399999999" } returns John Smith with all contacts annotated marketing_opt_in: false.
{ "phone": "0399999999", "require_marketing_optin": true } returns records: [] because John Smith has no opted-in contacts.
{ "gnaf_id": "GANSW716615055" } returns Mary Jones (the most-recent current resident), one record.
{ "gnaf_id": "GANSW716615055", "max_records": 5 } returns three records ordered most-recent first: Mary Jones, Peter Jones, Emily Tanner.
{ "gnaf_id": "GANSW716615055", "max_records": 5, "require_marketing_optin": true } returns Mary Jones and Peter Jones (each filtered down to their opt-in contacts); Emily Tanner is skipped because none of her contacts are opted in.
{ "gnaf_id": "GANSW716615055", "max_records": 5, "min_date_end": "2020-01-01" } returns Mary Jones and Peter Jones; Emily Tanner is excluded because her tenancy ended in 2019-07-19, before the supplied minimum.

Opt-in flag notes

Note that the optin flag is associated with the person and their email address or phone number, not the address. The address is returned for reference only and should not be assumed to be opted in for marketing.

Request body

Content type application/json. The lookup key and optional opt-in filter.

Field	Description
`phone`	string Australian phone number in `0NSN` (e.g. `0299995000`) or E.164 (e.g. `+61299995000`) format. Example: `0299995000`
`email`	string (email) Email address. Not case sensitive. Example: `mary_jones89@example.com`
`gnaf_id`	string GNAF address identifier. Example: `GANSW716615055`
`full_address`	string A single free-text Australian address. This will be parsed and resolved to a GNAF. Example: `35 Yaralla St, Concord West NSW 2138`
`street_address`	string Street address. Must be supplied together with `postcode`. `suburb` and `state` are optional but improve match accuracy. Example: `35 Yaralla St`
`suburb`	string Suburb. Optional - improves match accuracy when address parts are supplied. Example: `Concord West`
`state`	string State. Optional - improves match accuracy when address parts are supplied. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `NSW`
`postcode`	string Australian postcode. Required when `street_address` is supplied. Example: `2138`
`require_marketing_optin`	boolean When `true`, each returned record's phones and emails are filtered down to those explicitly opted in for marketing; persons left with no opted-in contacts are skipped entirely and we keep scanning further down the candidate list to fill the `max_records` quota. Defaults to `false`. Example: `false`
`max_records`	integer [1..25] The maximum number of person records to return in `records[]`. Persons are deduplicated by underlying identity before slicing, so a person who lived at the address across multiple tenancies counts as one record. Defaults to `1`. Range: `1` to `25`. Default: `1` Example: `5`
`min_date_end`	string (date) Optional ISO 8601 date (`YYYY-MM-DD`). Excludes candidate persons whose most-recent association ended before this date, before the `max_records` slice. Inclusive at the boundary (a `date_end` equal to `min_date_end` passes). Persons with a current / open-ended association (`date_end: null` in the response) are always kept. Example: `2020-01-01`

Responses

200

Result of the lookup.

application/json

Field	Description
`message`	string A message indicating the result of the request. This will be `Ok` for a successful response (including no-match results). Example: `Ok`
`function`	string The name of the API function that was called. Example: `marketing_contact_lookup`
`api_reference`	string (uuid) A unique identifier for this request. This can be used to track the request in the logs. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95`
`records`	array of objects Up to `max_records` matching person records, ordered most-recent first. Empty array when no match is found (or when `require_marketing_optin = true` and no matching person has any opted-in contacts).
`records[].title`	string The title (e.g. MR, MS) of the matched person. Example: `MS`
`records[].first_name`	string First name. Example: `MARY`
`records[].middle_name`	string Middle name. Example: `SALLY`
`records[].last_name`	string Last name. Example: `JONES`
`records[].dob`	string or null Date of birth (where known). Example: `1989-08-12`
`records[].dob_range_from`	string or null Earliest possible date of birth (used when the exact DOB is unknown).
`records[].dob_range_to`	string or null Latest possible date of birth (used when the exact DOB is unknown).
`records[].gender`	string Gender. Example: `FEMALE`
`records[].phones`	array of objects Phone numbers associated with this person, each annotated with a marketing opt-in flag.
`records[].phones[].phone`	string Phone number in 0NSN format. Example: `0299995000`
`records[].phones[].marketing_opt_in`	boolean Whether this phone number is explicitly opted in for marketing. Example: `true`
`records[].emails`	array of objects Email addresses associated with this person, each annotated with a marketing opt-in flag.
`records[].emails[].email`	string Email address. Example: `mary_jones89@example.com`
`records[].emails[].marketing_opt_in`	boolean Whether this email address is explicitly opted in for marketing. Example: `true`
`records[].address_id`	string GNAF address identifier. Example: `GANSW716615055`
`records[].street_address`	string Street address. Example: `35 YARALLA ST`
`records[].suburb`	string Suburb. Example: `CONCORD WEST`
`records[].state`	string State. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `NSW`
`records[].postcode`	string Postcode. Example: `2138`
`records[].date_start`	string or null First date the person was associated with this address. Example: `2016-06-09`
`records[].date_end`	string or null Last date the person was associated with this address. `null` for current / open-ended associations.
`records[].latitude`	string or null Latitude of the address. Example: `-33.84970097`
`records[].longitude`	string or null Longitude of the address. Example: `151.09426095`

Standard error responses: 400 401 402 403 429 5XX See common error responses

Previous Person History Next Deceased Check

Request body application/json

{
    "phone": "0299995000",
    "email": "mary_jones89@example.com",
    "gnaf_id": "GANSW716615055",
    "full_address": "35 Yaralla St, Concord West NSW 2138",
    "street_address": "35 Yaralla St",
    "suburb": "Concord West",
    "state": "NSW",
    "postcode": "2138",
    "require_marketing_optin": false,
    "max_records": 5,
    "min_date_end": "2020-01-01"
}

Response

200 Result of the lookup.

{
    "message": "Ok",
    "function": "marketing_contact_lookup",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "records": [
        {
            "title": "MS",
            "first_name": "MARY",
            "middle_name": "SALLY",
            "last_name": "JONES",
            "dob": "1989-08-12",
            "dob_range_from": null,
            "dob_range_to": null,
            "gender": "FEMALE",
            "phones": [
                {
                    "phone": "0299995000",
                    "marketing_opt_in": true
                }
            ],
            "emails": [
                {
                    "email": "mary_jones89@example.com",
                    "marketing_opt_in": true
                }
            ],
            "address_id": "GANSW716615055",
            "street_address": "35 YARALLA ST",
            "suburb": "CONCORD WEST",
            "state": "NSW",
            "postcode": "2138",
            "date_start": "2016-06-09",
            "date_end": null,
            "latitude": "-33.84970097",
            "longitude": "151.09426095"
        }
    ]
}

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}