# Caspar Person Autotrace

`POST /caspar_person_autotrace`

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

The Caspar Person Autotrace performs an automatic trace on the supplied person and associated contact details, returning possible matches ranked by a match score. The more information provided about the target person, the better the results and score ranking will be.

## Minimum Trace Requirements

At a minimum, a last name must be provided (`name_last` or `name_combined`). However, the quality of results will be lower without additional identifying information. The more information supplied (name, DOB, address, phone, email), the better the match scoring.

## Match Scoring

Each result includes a `score` field - a unitless integer where higher scores indicate a better match. The score takes into account multiple parameters including the distance between the supplied address and the matched address. If no address is supplied, the score may not be available.

## Relatives

Setting `option_relatives` to `true` will include possible relatives in the trace results. Relatives are people who have an association with the person being searched but do not match the person's full name. Each record includes a `match_type` field indicating whether it is a `primary` match or a `relative`.

## Sort Order

Result sorting is controlled by the `sort_by` and `sort_order` parameters. If no sort parameters are supplied, results are ordered by descending score, which is the most useful ordering for autotrace results.

## Performance

A single autotrace can perform tens to hundreds of internal searches to gather and rank results, which may take several seconds. Plan timeouts accordingly, particularly when performing multiple autotrace queries in sequence.

## Sandbox environment data

When simulating queries in the sandbox environment, the following records can be used to return results. Each example demonstrates multiple trace results with varying match scores.

### Multi-result examples

The following records return multiple trace results, demonstrating how autotrace ranks and returns possible matches:

| First Name | Last Name | Address | Trace Results | Description |
|:-----------|:----------|:--------|:--------------|:------------|
| Bernard | Williams | 1 MOJAVE DR, BURLEIGH WATERS QLD 4220 | 6 results | Strong primary match (score 1000) with 5 additional matches across QLD, SA, NSW, TAS, and WA |
| Kenneth | Hawkins | UNIT 46/10-12 FRENCH AV, BANKSTOWN NSW 2200 | 4 results | Four equally-scored matches (score 250) in the same state (NSW) |
| Peter | Clacher | 15 KEARSLEY ST, BELLBIRD NSW 2325 | 4 results | Primary match (score 1000) with diminishing scores across NSW, QLD, and WA |
| Paul | Hayes | UNIT 4/118 ELIZABETH DR, LIVERPOOL NSW 2170 | 4 results | Primary match (score 1000) with additional matches including phone and email details |
| Andrew | Sharp | 181-183 STATION RD, BURPENGARY QLD 4505 | 3 results | Primary match (score 1000) plus a name-variant match (Drew Sharp, score 16) |

### Single-result examples

The following records return a single strong match and are useful for testing basic autotrace functionality:

| Title | First Name | Last Name | Address | Phone | Email |
|:------|:-----------|:----------|:--------|:------|:------|
| MR | Owen | Wyllie | 4 BUTCHERBIRD CL, ELI WATERS QLD 4655 | 0741241873 | bc68@pardswit.org.au |
| MR | Peter | Jenkin | 2 TANAMI CL, BELROSE NSW 2085 | 0294511557, 0447336754 | peter508@moraitive.net.au |
| MS | Emma | Russell | 4 WESTMILL DR, HOPPERS CROSSING VIC 3029 | 0427519643 | |

## Request body

The details of the person to trace and any known contact information.

| 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 trace Example: `MARY` |
| `name_middle` | string | Middle name of the person to trace Example: `SALLY` |
| `name_last` | string | Last (family) name of the person to trace Example: `JONES` |
| `dob` | string (date) | Date of birth of the person to trace (YYYY-MM-DD) Example: `1989-08-12` |
| `phone1` | string | Known phone number of the person to trace Example: `0299995000` |
| `phone2` | string | Known phone number of the person to trace |
| `phone3` | string | Known phone number of the person to trace |
| `phone4` | string | Known phone number of the person to trace |
| `email1` | string (email) | Known email address of the person to trace Example: `mary_jones89@example.com` |
| `email2` | string (email) | Known email address of the person to trace |
| `email3` | string (email) | Known email address of the person to trace |
| `email4` | string (email) | Known email address of the person to trace |
| `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` |
| `option_relatives` | boolean | Include possible relatives in the trace results 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: `score`, `name`, `dob`, `phone`, `email`, `state`, `suburb`, `postcode`, `street_address`, `address_combined`, `updated` Example: `score` |
| `sort_order` | string | Sort direction Enum: `ASC`, `DESC` Example: `DESC` |

**Sample request**

```json
{
    "name_combined": "MARY JONES",
    "name_first": "MARY",
    "name_middle": "SALLY",
    "name_last": "JONES",
    "dob": "1989-08-12",
    "phone1": "0299995000",
    "phone2": "string",
    "phone3": "string",
    "phone4": "string",
    "email1": "mary_jones89@example.com",
    "email2": "user@example.com",
    "email3": "user@example.com",
    "email4": "user@example.com",
    "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",
    "option_relatives": true,
    "first_result": 0,
    "max_results": 10,
    "sort_by": "score",
    "sort_order": "DESC"
}
```

## Responses

### 200 Successful autotrace response with matching person records ranked by score.

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request: - `Ok` - Trace was successful - `No match` - No records found for this trace - `Found too many results` - The trace found too many results and was unable to provide useful scoring. Try providing more specific search criteria. Example: `Ok` |
| `function` | string | The API function that handled the request. Example: `caspar_person_autotrace` |
| `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, ordered by score (highest first) unless a different sort is specified. |
| `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[].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 | A unitless integer match score. Higher scores indicate a better match from the autotrace process. The score is based on multiple parameters including the distance between the supplied address and the matched address. Example: `1000` |
| `records[].match_type` | string | Relationship indicator to the searched record: - `primary` - Direct match against the primary record - `relative` - Match is a possible relative of the primary record Enum: `primary`, `relative` Example: `primary` |
| `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: `4` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "caspar_person_autotrace",
    "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"
                    }
                }
            },
            "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": "1000",
            "match_type": "primary",
            "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": 4
}
```

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