Global Data
Browse endpoints
View as Markdown OpenAPI spec

Caspar Person Search

POST /api/v2/caspar_person_search operationId: caspar_person_search

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

Content type application/json. The search criteria for finding people and their contact details.

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

Responses

200

Successful search response with matching person records.

application/json
FieldDescription
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
Standard error responses: 400 401 402 403 429 5XX See common error responses
Previous Retrieve a Business Intelligence Request Next Caspar Person Autotrace