Global Data Check

Validates a person's identity details against the Global Data Universe and returns one or more candidate match rows with per-field outcomes.

The endpoint searches by last_name and any combination of optional identifiers - birth_date, address, up to four phone numbers, and up to four email addresses. Every supplied field is then evaluated against each candidate and reported separately. last_name is the only required field.

Match outcomes

For first_name and middle_name the response uses a graded ladder. The strongest applicable label is returned:

Fields that the caller did not supply are omitted from each candidate row entirely. The address rollup key appears whenever any address part was supplied; individual address component keys (street_address, suburb, state, postcode) appear only when the caller actually supplied that part. When no address was supplied at all, the rollup and all four component keys are omitted together.

Which match types are accepted is controlled per name field via first_name_matching, middle_name_matching, and last_name_matching (defaults to ["exact"] for each).

For dob the outcomes are match, match_year (year matches but day/month don't), match_day_month_reversal (year matches, day and month swapped), no_record (candidate has no DOB on file), no_match, or not_used.

For phone and email, each supplied slot is evaluated independently against the candidate's full set of phones / emails. If you supply phone and phone3 (for example), the response carries a separate phone outcome and a separate phone3 outcome, each match / no_match based on whether that specific value matches any of the candidate's phones on file. Slots that the caller did not supply are omitted from the response. The same per-slot evaluation applies to email, email2, email3, and email4.

Australian phone numbers are accepted in either 0NSN form (10 digits starting with 0) or the equivalent E.164 form (+61 followed by 9 digits). The leading + on the E.164 form is optional - 61400123456 is accepted as well as +61400123456, which avoids spurious rejections of numbers that have round-tripped through Excel / CSV imports that silently strip the +. All three shapes are normalised to the 0NSN form internally before comparison.

Address matching

When an address is supplied, the response includes both an address rollup field and the four individual address component fields (street_address, suburb, state, postcode). The rollup is a single-glance summary of how well the supplied address matched the candidate; the component fields tell you exactly which parts agreed.

The rollup is derived from the components as follows:

The component fields each return match / no_match independently and are returned alongside the rollup so you can see which specific parts contributed to it. For example, address: match_street plus street_address: match and postcode: no_match tells you the candidate lives on the same street but in a different postcode area.

When the caller supplies only a subset of address parts (e.g. just postcode, or suburb + postcode), only those parts are evaluated and reported - the unsupplied address keys are omitted from the row entirely. The rollup match therefore means "every supplied part matched", not "all four parts matched".

Whichever input form was used (gnaf_id, full_address, or any combination of address parts), the supplied components are evaluated directly. With gnaf_id / full_address the address is resolved to canonical components first; with the parts form the supplied values are used as-is.

A given person may have several addresses on file (current and historical). match_results always returns one row per person - we do not duplicate the same person once per address. When evaluating, we score every address the person has against the supplied address and report the outcome for the best-matching one. Ties on rollup outcome are broken by preferring the most recently active address. For example, if a person has both an old match_locality address and a current match address against your input, you will see address: match in the response.

Best-candidate selection

Candidates are ranked in three steps, applied in order:

1. Strong-discriminator hits rank first. A candidate that produces an exact match against any of phone, email, full dob, or the full address (the rollup at match) outranks any candidate that does not, regardless of how well the other candidate scores on names alone. dob: match_day_month_reversal also counts as a strong-discriminator hit, but only when the candidate also has first_name of match / alias_match AND last_name of match - without name corroboration, a reversed DOB is treated as a numeric coincidence and does not gate the candidate into the strong-discriminator group.
2. Exact last-name wins within the strong-discriminator group. Among candidates in the same group from step 1, candidates with last_name: match rank above candidates with last_name: fuzzy_match - a fuzzy last-name candidate never displaces an exact last-name candidate for the top slot.
3. Weighted score breaks remaining ties. Per-field weights are summed and the highest sum wins:

Each candidate row reports the per-field outcomes directly. Callers wanting to drive a routing rule should branch on the specific outcomes that matter for their use case (for example, last_name: match plus dob: match plus any phone match for high-confidence auto-approval) rather than on a single aggregate score.

Single vs multiple candidates

match_results is always an array, with one row per distinct person in the universe (never one row per person-and-address). By default the array contains the single best candidate (length 0 or 1). Set return_multiple_candidates: true to receive multiple candidates ordered best-first, with the same row schema.

When return_multiple_candidates: true is set, the response is capped at the top 5 candidates by score. If your search matches more than 5 records, only the strongest 5 are returned. Narrow your request (add a DOB, a phone, or an address) to lift the strongest candidates above the cap.

Two universe records that produce identical per-field outcomes against the request collapse into a single row in match_results. The count of rows therefore reflects the number of distinct outcome maps, not the number of underlying universe records considered. Adding more identifiers to the request makes candidates differ in their per-field outcomes and surface as separate rows.

ignore_errors

Useful when the data you are checking is not perfectly clean - for example, when the source system you are pulling from contains the occasional malformed phone number, invalid email, or junk date of birth.

By default, any individual field that fails validation will cause the whole request to be rejected with a 400 error, leaving you to either retry the call with the bad fields omitted or fix the data on your side first.

Setting ignore_errors: true removes that round-trip: the endpoint silently drops any individual field whose value fails validation (a malformed birth_date, an invalid phone number, an unresolvable address, etc.) and runs the match against whatever valid input remains. The dropped fields are reported back in the response as not_used so you can see exactly which inputs were ignored. Only field-level value problems are soft-ignored - the request still has to be structurally well-formed (correct types, last_name present).

include_deceased

Records marked as deceased are excluded from the candidate pool by default. Setting include_deceased: true adds them back in.

Note that the response does not include any indicator of whether a returned candidate was deceased - matched candidates are returned in the same shape regardless. Most use cases (KYC, identity verification, contact validation) should leave this off; only enable it when you have a specific need to match against deceased records and your downstream workflow handles them appropriately.

Sandbox environment

When simulating queries in the sandbox environment, the following records can be searched for:

Useful demonstrations against the sandbox data:

• alias_match - search first_name = "Bob", last_name = "Brown", birth_date = "1971-03-18" with first_name_matching = ["exact","alias"] matches Robert Brown with first_name: alias_match.
• partial_match - search first_name = "Robert", last_name = "Brown" with first_name_matching = ["exact","partial"] may match the R BROWN record with first_name: partial_match.
• fuzzy_match - search first_name = "Mathew", last_name = "Smith", birth_date = "1999-10-21" with first_name_matching = ["exact","fuzzy"] matches Matthew Smith with first_name: fuzzy_match.
• address as identifier - search last_name = "Smith" plus the full address 20 HARDY ST, LILYDALE 3140 VIC (no other identifier) matches John Smith.
• last-name-only - search last_name = "Evans" with return_multiple_candidates = true returns every Evans in the universe, including Joan Evans.
• no_record DOB - search first_name = "Robert", last_name = "Brown", phone = "0491222333", birth_date = "1985-06-04" matches the second Robert Brown record by phone, with dob: no_record because that record has no DOB on file.