# Caspar Person Search

`POST /caspar_person_search`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/caspar_person_search`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/caspar_person_search`

The Caspar Person Search returns a list of people and contact details based on the supplied search parameters. The search can be performed using a combination of name, address, phone number and email address.

## Search Types

The person search can be used in a number of ways using different parameters and parameter combinations:

- **Name Search**: Searching for a name (or partial name) will return all people matching that name along with their address and any associated phone numbers and email addresses. An optional DOB range can also be included.
- **Phone Search**: Searching for a phone number (or partial phone number) will return all people connected to that phone number along with their address and any additional associated phone numbers and email addresses.
- **Email Search**: Searching for an email address will return all people connected to that email along with their address and any additional associated phone numbers and email addresses.
- **IP Address Search**: Searching for an IP address will return all people who have an online record associated with that IP address. Only IPv4 addresses are supported; IPv6 addresses are not currently supported.
- **Social Search**: Searching for a social media profile URL will return all people connected to that social profile. Supported social networks include Facebook, LinkedIn, Twitter, YouTube, Instagram, Indeed, Github, Meetup, Quora, Gravatar, Foursquare, and Pinterest. The URL can include or omit the `http://`/`https://` scheme and an optional leading `www.`, for example, `facebook.com/person123`, `www.facebook.com/person123`, and `https://www.facebook.com/person123` will all match the same person.
- **Address Search**: Searching for an address will return all people (current and historical) at that address along with any associated phone numbers and email addresses. It is also possible to search for an entire street and return all addresses and people on that street.

## Search Operation

By default, the search returns records which match **all** of the supplied elements using a logical AND:

> Name **AND** Address **AND** Phone **AND** Email **AND** IP Address **AND** Social

However, many end users prefer a mode where the name and address are searched together, but records matching just the phone, email, IP address, or social profile are returned as well. This is accomplished by enabling the `option_smartsearch` option, in which case the logic becomes:

> (Name **AND** Address) **OR** Phone **OR** Email **OR** IP Address **OR** Social

## Minimum Search Requirements

At least one of the following must be provided:
- `name_last` or `name_combined`
- `phone`
- `email`
- `ip_address`
- `social_url`
- `full_address` or `street_address`

A name search requires at least the last name. A name and partial address search is permitted for:

| Search | Records Returned |
|:-------|:-----------------|
| Name and state | All occurrences of the name in the state |
| Name and suburb | All occurrences of the name in the suburb |
| Name and postcode | All occurrences of the name in the postcode |
| Name and street (+ suburb/state/postcode) | All occurrences of the name on the street |

## DOB Searching

A name search can be combined with DOB bounds (`dob_from` and/or `dob_to`) to restrict results to records where a DOB falls within the specified range. Supplying only one bound will return results above or below the specified date.

## Smart Options

| Option | Effect |
|:-------|:-------|
| `option_smartname` | Matches initials, first-name equivalents (Robert = Bob/Rob), and similar-sounding last names (Smith = Smyth) |
| `option_smartemail` | Matches the email username across different domains and TLDs |
| `option_smartphone` | Matches partial phone numbers across area codes and mobile prefixes |
| `option_smartaddress` | Matches similar or misspelled addresses in the selected area or neighbouring suburbs |
| `option_smartsearch` | Changes search logic to: (Name AND Address) OR Phone OR Email OR IP Address OR Social |

## Sort Order

Result sorting is controlled by the `sort_by` and `sort_order` parameters. If no sort parameters are supplied, results are returned in a default order that takes into account the search parameters and attempts to place the most relevant results first.

## Secondary Person Search

A secondary person can be included in the search using the `secondary_name_*` and `secondary_dob_*` parameters. This will search for both people at the same address.

## Sandbox environment data

When simulating queries in the sandbox environment, the following records can be used to return results:

### Sample records

| Title | First Name | Middle Name | Last Name | Street Address | Suburb | State | Postcode | Phone | Email |
|:------|:-----------|:------------|:----------|:---------------|:-------|:------|:---------|:------|:------|
| MS | Emma | Sandra | Russell | 4 Westmill Dr | Hoppers Crossing | VIC | 3029 | 0427519643 | |
| | Shaun | | Pound | 18 Ardisia Ct | Burleigh Heads | QLD | 4220 | 0436991031, 0755687356 | pdffyr41@denceads.com.au |
| MR | William | | Angell | 16 Hex St | West Footscray | VIC | 3012 | | ml1972@listratence.net.au |

### Sample marketing_opt_in flags

When `option_marketing_opt_in=true` is sent, the sample records above resolve to the following opt-in flags so that callers can observe both `true` and `false` values:

| Person | Contact | marketing_opt_in |
|:-------|:--------|:-----------------|
| Emma Sandra Russell | phone 0427519643 | `true` |
| Shaun Pound | phone 0436991031 | `true` |
| Shaun Pound | phone 0755687356 | `false` |
| Shaun Pound | email pdffyr41@denceads.com.au | `true` |
| William Angell | email ml1972@listratence.net.au | `false` |

### Addresses with deep history

Searching for the following addresses will return multiple residents demonstrating deep address history:

| Address | Expected Records |
|:--------|:-----------------|
| 375 ARGENT ST, BROKEN HILL NSW 2880 | 10 residents |
| UNIT 4/88 BROOK ST, COOGEE NSW 2034 | Multiple residents |
| 42 HOFF ST, MOUNT GRAVATT EAST QLD 4122 | Multiple residents |

## Request body

The search criteria for finding people and their contact details.

| Field | Type | Description |
|-------|------|-------------|
| `name_combined` | string | The full name to search for as a single string (e.g. "MARY SALLY JONES") Example: `MARY JONES` |
| `name_first` | string | First name of the person to search Example: `MARY` |
| `name_middle` | string | Middle name of the person to search Example: `SALLY` |
| `name_last` | string | Last (family) name of the person to search Example: `JONES` |
| `dob_from` | string (date) | Lower bound date of birth (YYYY-MM-DD) Example: `1980-01-01` |
| `dob_to` | string (date) | Upper bound date of birth (YYYY-MM-DD) Example: `1995-12-31` |
| `secondary_name_first` | string | First name of a second person to search (same address) Example: `JOHN` |
| `secondary_name_middle` | string | Middle name of the second person to search |
| `secondary_name_last` | string | Last (family) name of the second person to search Example: `JONES` |
| `secondary_dob_from` | string (date) | Lower bound DOB of the second person (YYYY-MM-DD) |
| `secondary_dob_to` | string (date) | Upper bound DOB of the second person (YYYY-MM-DD) |
| `street_address` | string | First line of the street address Example: `35 YARALLA ST` |
| `suburb` | string | Suburb of the address Example: `CONCORD WEST` |
| `state` | string | Australian state of the address Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `NSW` |
| `postcode` | string | Postcode of the address Example: `2138` |
| `suburb_state_postcode` | string | A single string containing the suburb, state and postcode (address line 2) Example: `CONCORD WEST NSW 2138` |
| `full_address` | string | A single string containing the complete address Example: `35 YARALLA ST CONCORD WEST NSW 2138` |
| `phone` | string | Phone number of the person to search Example: `0299995000` |
| `email` | string (email) | Email address of the person to search Example: `mary_jones89@example.com` |
| `ip_address` | string (ipv4) | IPv4 address to search for. Returns people who have an online record associated with this IP address. IPv6 addresses are not currently supported. Example: `203.0.113.42` |
| `social_url` | string | Social media profile URL to search for. Returns people connected to the specified social profile. The URL can include or omit the `http://`/`https://` scheme and an optional leading `www.`. Supported social networks: Facebook, LinkedIn, Twitter, YouTube, Instagram, Indeed, Github, Meetup, Quora, Gravatar, Foursquare, and Pinterest. Example: `facebook.com/person123` |
| `option_smartname` | boolean | Enable smart name matching (initials, equivalents, similar-sounding) Default: `false` |
| `option_smartemail` | boolean | Enable smart email matching (cross-domain, cross-TLD) Default: `false` |
| `option_smartphone` | boolean | Enable smart phone matching (partial numbers, cross-area-code) Default: `false` |
| `option_smartaddress` | boolean | Enable smart address matching (similar/misspelled addresses, neighbouring suburbs) Default: `false` |
| `option_smartsearch` | boolean | Enable smart search mode which changes the search logic to: (Name AND Address) OR Phone OR Email Default: `false` |
| `option_marketing_opt_in` | boolean | Include a `marketing_opt_in` block on each record indicating whether each phone number and email address is registered as opted-in for marketing for this specific person. Opt-in is determined per-person, per-contact: the same email or phone may be opted-in for one person but not for another (an email shared by partners, for example, can be marketing-opted-in for only one of them). A value of `true` means an explicit opt-in record exists for that contact under that person; `false` means that no opt-in record exists. Note that the opt-in status on a phone number does not negate the requirement to perform a DNC check on the phone number before attempting to call the person. Default: `false` |
| `first_result` | integer [min 0] | Index of first result to return for pagination (0-based) Default: `0` Example: `0` |
| `max_results` | integer [1..30] | Maximum number of results to return (1-30) Default: `10` Example: `10` |
| `sort_by` | string | Field to sort results by Enum: `name`, `dob`, `phone`, `email`, `state`, `suburb`, `postcode`, `street_address`, `address_combined`, `updated` Example: `name` |
| `sort_order` | string | Sort direction Enum: `ASC`, `DESC` Example: `ASC` |

**Sample request**

```json
{
    "name_combined": "MARY JONES",
    "name_first": "MARY",
    "name_middle": "SALLY",
    "name_last": "JONES",
    "dob_from": "1980-01-01",
    "dob_to": "1995-12-31",
    "secondary_name_first": "JOHN",
    "secondary_name_middle": "string",
    "secondary_name_last": "JONES",
    "secondary_dob_from": "2024-01-01",
    "secondary_dob_to": "2024-01-01",
    "street_address": "35 YARALLA ST",
    "suburb": "CONCORD WEST",
    "state": "NSW",
    "postcode": "2138",
    "suburb_state_postcode": "CONCORD WEST NSW 2138",
    "full_address": "35 YARALLA ST CONCORD WEST NSW 2138",
    "phone": "0299995000",
    "email": "mary_jones89@example.com",
    "ip_address": "203.0.113.42",
    "social_url": "facebook.com/person123",
    "option_smartname": true,
    "option_smartemail": true,
    "option_smartphone": true,
    "option_smartaddress": true,
    "option_smartsearch": true,
    "option_marketing_opt_in": true,
    "first_result": 0,
    "max_results": 10,
    "sort_by": "name",
    "sort_order": "ASC"
}
```

## Responses

### 200 Successful search response with matching person records.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request: - `Ok` - Search was successful - `No match` - No records found for the search criteria - `Found too many results` - The search matched too many records. Try providing more specific search criteria. Example: `Ok` |
| `function` | string | The API function that handled the request. Example: `caspar_person_search` |
| `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 | Array of matching person records. |
| `records[].title` | string | Title of the matched person Example: `MS` |
| `records[].first_name` | string | First name of the matched person Example: `MARY` |
| `records[].middle_name` | string | Middle name of the matched person Example: `SALLY` |
| `records[].last_name` | string | Last name of the matched person Example: `JONES` |
| `records[].dob` | string | Date of birth (year only, format YYYY) if available Example: `1989` |
| `records[].dob_range_from` | string | DOB range minimum (year only, format YYYY) if no exact DOB is available Example: `` |
| `records[].dob_range_to` | string | DOB range maximum (year only, format YYYY) if no exact DOB is available Example: `` |
| `records[].deceased` | string | Deceased flag Enum: `Y`, `N` Example: `N` |
| `records[].deceased_date` | string | Deceased date (year only, format YYYY) if available Example: `` |
| `records[].gender` | string | Gender of the matched person Enum: `MALE`, `FEMALE`, `X`, `UNKNOWN` Example: `FEMALE` |
| `records[].phones` | array of strings | Array of phone numbers associated with the matched person |
| `records[].emails` | array of strings | Array of email addresses associated with the matched person |
| `records[].socials` | array of objects | Social media accounts associated with the matched person (if available) |
| `records[].ip_addresses` | array of strings | IP addresses associated with the matched person (if available) |
| `records[].connectivity` | object | Cached connectivity check results for any phones and emails in the result set. Each entry is keyed by the phone number or email address itself. Arrays may be empty when no cached connectivity data is available. Real-time connectivity can be obtained via the `email_ping` and `phone_ping` endpoints. |
| `records[].connectivity.phones` | object (dynamic) | Cached phone ping results keyed by phone number. Only populated when a cached ping result exists for a phone number in the result set. |
| `records[].connectivity.emails` | object (dynamic) | Cached email ping results keyed by email address. Only populated when a cached ping result exists for an email address in the result set. |
| `records[].marketing_opt_in` | object | Per-contact marketing opt-in status for this person. Only present when `option_marketing_opt_in=true` was sent on the request. `true` indicates the contact is registered as opted-in for marketing for this specific person; `false` indicates either no opt-in record exists, the contact is not in the local marketing dataset, or this person could not be matched locally. Opt-in status is per-person-per-contact - the same email or phone may resolve to `true` for one person and `false` for another. |
| `records[].marketing_opt_in.phones` | object (dynamic) | Marketing opt-in flag keyed by phone number. Contains an entry for every phone number in the record's `phones` array. |
| `records[].marketing_opt_in.emails` | object (dynamic) | Marketing opt-in flag keyed by email address. Contains an entry for every email address in the record's `emails` array. |
| `records[].address_id` | string | Address persistent identifier Example: `GANSW716615055` |
| `records[].street_address` | string | The street/postal address as one string Example: `35 YARALLA ST` |
| `records[].suburb` | string | Suburb of the matched address Example: `CONCORD WEST` |
| `records[].state` | string | State of the matched address Example: `NSW` |
| `records[].postcode` | string | Postcode of the matched address Example: `2138` |
| `records[].address_parsed` | string | Whether the address passed the address parser (Y/N) Enum: `Y`, `N` Example: `Y` |
| `records[].address_valid` | string | Whether the address exists in the address table (Y/N) Enum: `Y`, `N` Example: `Y` |
| `records[].address_primary_secondary` | string | Whether address is a primary or secondary dwelling (P/S or blank) Example: `` |
| `records[].date_start` | string | Date the person was first seen at this address (YYYY-MM) Example: `2016-06` |
| `records[].date_end` | string | Date the person was last seen at this address (YYYY-MM) Example: `2019-07` |
| `records[].legal_parcel_id` | string | Legal parcel identifier for the address property Example: `15//DP240258` |
| `records[].meshblock_category` | string | ABS meshblock category for the address (e.g. Residential, Commercial, Parkland) Example: `Residential` |
| `records[].latitude` | string | Latitude coordinate of the address Example: `-33.72914350` |
| `records[].longitude` | string | Longitude coordinate of the address Example: `151.21036778` |
| `records[].score` | string | Match relevance score. For person search this is typically "0"; for autotrace results this is a meaningful ranking score. Example: `0` |
| `records[].realestate` | array of objects | Real estate events for this address |
| `records[].realestate[].listing_type` | string | Type of listing: sale, sold, or rent Enum: `sale`, `sold`, `rent` |
| `records[].realestate[].property_type` | string | Type of property (e.g. House, Apartment, Unit) |
| `records[].realestate[].num_bedrooms` | string | Number of bedrooms (if available) |
| `records[].realestate[].num_bathrooms` | string | Number of bathrooms (if available) |
| `records[].realestate[].num_car_spaces` | string | Number of car spaces (if available) |
| `records[].realestate[].date` | string (date) | Date of the listing (YYYY-MM-DD) |
| `records[].realestate[].estate_agent` | string | Name of the estate agent |
| `records[].realestate[].price` | string | Property price (where available) |
| `records[].judgements` | array of objects | Judgements or events for the person at this address |
| `records[].judgements[].name` | string | The name for which the judgement is recorded |
| `records[].judgements[].creditor` | string | Name of the creditor |
| `records[].judgements[].event` | string | Description of the event |
| `records[].judgements[].date` | string (date) | Date of listing (YYYY-MM-DD) |
| `records[].business` | array of objects | ABN records possibly associated with the person at the matched postcode |
| `records[].business[].abn` | string | ABN of the matching entity Example: `12345678901` |
| `records[].business[].status` | string | ABN status: ACT (Active) or CAN (Cancelled) Enum: `ACT`, `CAN` |
| `records[].business[].effective_from` | string (date) | Date the status became effective (YYYY-MM-DD) |
| `records[].address_info` | array of objects | Additional information about the address |
| `records[].address_info[].property_type` | string | Type of property: agedcare, prison, or emg_accom Enum: `agedcare`, `prison`, `emg_accom` |
| `records[].address_info[].property_detail` | string | Description of the property |
| `records[].demographic` | object | SEIFA geo-demographic indices for the address area, based on SA1 level statistical analysis. Decile ranked from 0 to 10, where 10 indicates the top 10% of areas for that indicator and 0 means no data is available. |
| `records[].demographic.IRSAD_decile` | string | Index of Relative Socio-economic Advantage and Disadvantage (0-10). Focuses on financial aspects related to buying power, income and wealth. A low score indicates relative disadvantage (e.g. low income households); a high score indicates relative advantage (e.g. high income, home ownership). Example: `9` |
| `records[].demographic.IER_decile` | string | Index of Economic Resources (0-10). Focuses on financial aspects related to buying power, income and wealth. A low score indicates a relative lack of economic resources (e.g. low income, low rent); a high score indicates greater access to economic resources (e.g. high income, home ownership). Example: `8` |
| `records[].demographic.IEO_decile` | string | Index of Education and Occupation (0-10). Focuses on the educational and occupational level of the area. A low score indicates lower education and occupation status (e.g. no qualifications, low skilled or unemployed); a high score indicates higher education and occupation status (e.g. higher qualifications, highly skilled occupations). Example: `7` |
| `records[].court_record` | string or null | Whether a court record exists for this person (Y/N or null if not checked) Enum: `Y`, `N` Example: `N` |
| `records[].social_record` | string or null | Whether a social media record exists for this person (Y/N or null if not checked) Enum: `Y`, `N` Example: `N` |
| `records[].employment_record` | string or null | Whether an employment record exists for this person (Y/N or null if not checked) Enum: `Y`, `N` Example: `N` |
| `records[].sources` | array of strings | Data sources that contributed to this record (e.g. government, proprietary_records, competition). May be empty. |
| `total_records_available` | integer | Total number of matching records available. Example: `1` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "caspar_person_search",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "records": [
        {
            "title": "MS",
            "first_name": "MARY",
            "middle_name": "SALLY",
            "last_name": "JONES",
            "dob": "1989",
            "dob_range_from": "",
            "dob_range_to": "",
            "deceased": "N",
            "deceased_date": "",
            "gender": "FEMALE",
            "phones": [
                "0299995000",
                "0491999888"
            ],
            "emails": [
                "mary_jones89@example.com"
            ],
            "socials": [],
            "ip_addresses": [
                "string"
            ],
            "connectivity": {
                "phones": {
                    "0299995000": {
                        "check_date": "2020-03-23",
                        "status": "connected",
                        "carrier": "",
                        "geo_area": "Sydney",
                        "dnc_result": "",
                        "dnc_check_date": "",
                        "dnc_reference": ""
                    },
                    "0491999888": {
                        "check_date": "2020-08-04",
                        "status": "disconnected",
                        "carrier": "Telstra",
                        "geo_area": "",
                        "dnc_result": "N",
                        "dnc_check_date": "2020-08-04",
                        "dnc_reference": ""
                    }
                },
                "emails": {
                    "mary_jones89@example.com": {
                        "check_date": "2020-08-04",
                        "status": "undeliverable"
                    }
                }
            },
            "marketing_opt_in": {
                "phones": {
                    "0299995000": true,
                    "0491999888": false
                },
                "emails": {
                    "mary_jones89@example.com": true
                }
            },
            "address_id": "GANSW716615055",
            "street_address": "35 YARALLA ST",
            "suburb": "CONCORD WEST",
            "state": "NSW",
            "postcode": "2138",
            "address_parsed": "Y",
            "address_valid": "Y",
            "address_primary_secondary": "",
            "date_start": "2016-06",
            "date_end": "2019-07",
            "legal_parcel_id": "15//DP240258",
            "meshblock_category": "Residential",
            "latitude": "-33.72914350",
            "longitude": "151.21036778",
            "score": "0",
            "realestate": [
                {
                    "listing_type": "sale",
                    "property_type": "string",
                    "num_bedrooms": "string",
                    "num_bathrooms": "string",
                    "num_car_spaces": "string",
                    "date": "2024-01-01",
                    "estate_agent": "string",
                    "price": "string"
                }
            ],
            "judgements": [
                {
                    "name": "string",
                    "creditor": "string",
                    "event": "string",
                    "date": "2024-01-01"
                }
            ],
            "business": [
                {
                    "abn": "12345678901",
                    "status": "ACT",
                    "effective_from": "2024-01-01"
                }
            ],
            "address_info": [
                {
                    "property_type": "agedcare",
                    "property_detail": "string"
                }
            ],
            "demographic": {
                "IRSAD_decile": "9",
                "IER_decile": "8",
                "IEO_decile": "7"
            },
            "court_record": "N",
            "social_record": "N",
            "employment_record": "N",
            "sources": [
                "government",
                "proprietary_records"
            ]
        }
    ],
    "total_records_available": 1
}
```

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