# 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 lookup key
(a contact detail, an address, or a name plus postcode) 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) |
| Name + postcode | `full_name` plus `postcode`. See *Name lookups* below. |

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

## Name lookups

A name on its own is not a reliable lookup key, so `full_name` must always be paired with a
`postcode`. We split the name into first / middle / last parts using the same name rules our
universe is built with, so any of these forms work:

- `"John Smith"`
- `"Smith, John"` or `"Smith, John Andrew"` (surname first with a comma)
- `"Mr John A Smith"` (titles are ignored)
- `"Trent van der Berg"` (multi-word surnames are kept whole)

First and last name are then matched **exactly** (case-insensitive) against persons who have,
or have had, an address in the supplied postcode. Initials and spelling variants are not
expanded: `"J Smith"` will not find `JOHN SMITH`. A middle name, if supplied, is **never used
to filter**; it only ranks persons whose middle name matches ahead of the others (a middle
initial such as `"Mary S Jones"` ranks `SALLY` ahead too). After that, records follow the
normal most-recent-first order.

`full_name` takes `postcode` and nothing else: sending `suburb` or `state` with it returns a
`400`, as does combining it with any other lookup key. The postcode is a hard filter: the
address returned for each person is their most recent address **within the requested
postcode**, even if they have since moved elsewhere. Use `min_date_end` if you only want
people whose association with that postcode is recent.

The request is rejected with a `400` when the name cannot be split into a single person with
both a first and a last name - for example a surname only (`"Smith"`), a couple
(`"John and Jenny Smith"`), or a name containing digits.

Because common names will match more than one person in a postcode, we recommend callers
using this variant set `max_records` above `1` and present the candidates to their user
rather than assuming the first record is the right person.

## 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.
- `{ "full_name": "John Smith", "postcode": "3140" }` returns John Smith at 20 HARDY ST, LILYDALE.
- `{ "full_name": "Jones, Mary", "postcode": "2138" }` returns Mary Jones.
- `{ "full_name": "John Smith", "postcode": "2000" }` returns `records: []` because John Smith has no address in that postcode.
- `{ "full_name": "Smith", "postcode": "3140" }` returns a `400` because a surname alone is not accepted.

## 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 (a contact detail, an address, or a full name plus postcode) and optional filters.

| 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. Not accepted with `full_name`. Example: `Concord West` |
| `state` | string | State. Optional - improves match accuracy when address parts are supplied. Not accepted with `full_name`. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `NSW` |
| `postcode` | string | Australian postcode. Required when `street_address` or `full_name` is supplied. Example: `2138` |
| `full_name` | string [max 80 characters] | A person's full name, e.g. `John Smith`, `Smith, John Andrew` or `Trent van der Berg`. Must be supplied together with `postcode`. Split into first / middle / last name using our name rules; first and last name are matched exactly, a middle name only affects ranking. Must describe a single person with both a first and a last name. Example: `John Smith` |
| `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",
    "full_name": "John Smith",
    "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))

