# Marketing Contact Lookup `POST /marketing_contact_lookup` - Live: `POST https://gdapi.globaldata.net.au/api/v2/marketing_contact_lookup` - Sandbox: `POST 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 The lookup key and optional opt-in filter. | Field | Type | 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` | **Sample request** ```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" } ``` ## Responses ### 200 Result of the lookup. Content type: `application/json` | Field | Type | 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` | **Sample response** ```json { "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" } ] } ``` Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))