Global Data
Browse endpoints
View as Markdown OpenAPI spec

Caspar Person Autotrace

POST /api/v2/caspar_person_autotrace operationId: caspar_person_autotrace

Live: https://gdapi.globaldata.net.au/api/v2/caspar_person_autotrace · Sandbox: 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

Content type application/json. The details of the person to trace and any known contact information.

FieldDescription
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

Responses

200

Successful autotrace response with matching person records ranked by score.

application/json
FieldDescription
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
Standard error responses: 400 401 402 403 429 5XX See common error responses
Previous Caspar Person Search Next ASIC Company Search