Person Report

POST /api/v2/person_report operationId: person_report

Live: https://gdapi.globaldata.net.au/api/v2/person_report · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/person_report

Experimental

The Person Report API is still in the experimental stage and is subject to change.

Takes whatever you know about a person - a name, a date of birth, an address or locality, a phone number, an email address, or any combination - resolves it to a single person in the Global Data universe, and returns a consolidated report of everything held about them.

Resolution is iterative: each source consulted (the person universe, the ASIC person register, the commercial universe, social enrichment) can return new identifiers, which feed the next round of searches until no new information appears. Every fact in the report cites the lookup it came from, and a plain-English research log records what was searched, what was found, what was decided and what was rejected.

Asynchronous

The request is queued and answered immediately with an acknowledgement carrying a request_uuid and result_url - nothing else. Poll GET /person_report/{request_uuid} (free) until status is complete; the full report response (search_criteria, resolution, report, provenance) is documented on that endpoint. Results are retained for 24 hours.

Resolution outcomes

The resolution.outcome field tells you what happened. Only a resolved outcome carries a report.

Outcome	Meaning	What to do
`resolved`	One subject was identified with `medium` or `high` confidence.	Read the `report`.
`low_confidence`	One candidate matched on name only; the details you supplied did not corroborate it.	Confirm with the `candidate_token`, or add a phone / email / date of birth.
`ambiguous`	Several people match. A redacted candidate list is returned.	Re-submit with the `candidate_token` of the right person, or add narrowing details.
`too_many`	The name is too common to list. Distribution hints are returned.	Add a date of birth, postcode, phone or email.
`not_found`	Nothing matched.	Check the details; try a different identifier.

Date of birth is treated as evidence, not a key: a supplied date that is a day out, or has the day and month swapped, will still match and is reported as a near_miss. Where sources disagree the report lists every date seen in birth_date_candidates with its supporting votes.

Sections

Every report is as comprehensive as the sources allow. It always contains identity, addresses (an address timeline - each entry carries the subject's tenure, occupancy, the other people seen at that address with their overlap, and real-estate events there), contacts, household (possible relatives - co-residents sharing the surname, extended to every same-surname person when the surname is rare), business, asic, companies_house (UK Companies House officer records and appointments, matched on name and birth month), watchlists, court (court record summaries, matched on name and labelled as unverified), adverse_media (an AI-assisted search of news, regulator and public web sources on the subject's name, with a machine-written summary and the articles it drew on - matched on name only and labelled as unverified), judgements and social (professional profile, employment history and social profile URLs, where a social profile matches one of the subject's phones or emails and carries the subject's name).

Every section carries a status of ok, empty, clear (watchlists), skipped or error, so one unavailable source never fails the whole report.

A resolved report opens with a summary: who was resolved and on what evidence, what was found, which findings are name-only leads, and what to verify next. On live reports it is written by an AI language model from a redacted digest of the finished report (no phone, email, street address, full date of birth or relative's name leaves the report); a templated summary with the same parts stands in when the model is unavailable and in the sandbox.

No artificial intelligence is used to resolve the identity or match records. The adverse_media section and the AI-written summary are the only AI-assisted parts, and both say so.

Provenance

provenance.sources lists every lookup performed (with the exact query, dataset or provider, round and result count), provenance.inferences every conclusion drawn (with the rule applied and the evidence it rests on), and provenance.research_notes the chronological research log. Facts in the report cite source ids (S1, S2, ...) and inference ids (I1, I2, ...). Provenance is always returned in full, so every report arrives with its complete audit trail.

Sandbox environment data

The sandbox runs against the sample universe. Useful inputs:

Input	Outcome
`first_name: John`, `last_name: Smith`, `birth_date: 1998-03-21`	`resolved` - full report including real-estate events on the address timeline, an ASIC officeholder record, a PEP match, court records, a judgement, a full social profile, a co-resident relative, UK Companies House officer and disqualified-director records, ASIC banned and ATO disqualified trustee matches, and an adverse media hit
`first_name: John`, `last_name: Smith`, `birth_date: 1998-03-21`, `emails: ["john@smithjoinery.com"]`	`resolved` - as above, plus a business section: a sole-trader ABN linked on postcode, SMITH JOINERY associated through the email domain, and one namesake ABN holder elsewhere not linked
`phones: ["0427151494"]`	`resolved` - Robert Patrick Brown, two universe rows merged on a shared email
`emails: ["jsmith1998@example.com"]`	`resolved`
`first_name: Robert`, `last_name: Brown`	`ambiguous` - two candidates with `candidate_token`s
`first_name: Mary`, `last_name: Jones`	`resolved` on a rare name alone
`first_name: Aaron`, `last_name: Wolfe`	`resolved` with Ruth Wolfe as a possible relative

Sample report

A complete report touching every section, generated in the sandbox from first_name: John, last_name: Smith, birth_date: 1998-03-21, emails: ["john@smithjoinery.com"]. Submit the same request in the sandbox and poll with pdf=true to reproduce it. Sandbox PDFs carry a SAMPLE watermark: the data is fictional and describes no real person.

Request body

Content type application/json. Whatever is known about the person. At least a first and last name, a phone, an email, or a candidate token is required.

Field	Description
`first_name`	string First (given) name. Common equivalents (Tony / Antonio, Bob / Robert) are searched automatically. Example: `John`
`middle_name`	string or null Middle name(s), if known. Example: `Andrew`
`last_name`	string Surname. Matched exactly - make sure the spelling is right. Example: `Smith`
`birth_date`	string (date) or null Date of birth in ISO 8601 (`YYYY-MM-DD`) - other formats are rejected. Treated as evidence - near misses still match and are reported. Example: `1998-03-21`
`phones`	array of strings [max 4 items] Up to four Australian phone numbers in 0NSN or +61 format, de-duplicated after normalisation.
`emails`	array of strings [max 4 items] Up to four email addresses, de-duplicated.
`street_address`	string or null A street address the person is known at (e.g. "20 Hardy Street"). Strongly corroborates a candidate seen at that address; street types are matched loosely ("Street" == "St"). Combine with `suburb` / `state` / `postcode` to pin the locality. Example: `20 Hardy Street`
`suburb`	string or null Suburb, as a narrowing input. Example: `Lilydale`
`state`	string or null State, as a narrowing input. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `VIC`
`postcode`	string or null Postcode, as a narrowing input. Example: `3140`
`candidate_token`	string or null A token from a previous `ambiguous` or `low_confidence` response selecting one candidate. Valid for one hour, in the same environment only.

Responses

200

Request accepted and queued. This response is an acknowledgement only - poll `GET /person_report/{request_uuid}` for the result, which is documented on that endpoint.

application/json

Field	Description
`message`	string Example: `Ok`
`function`	string Example: `person_report`
`api_reference`	string (uuid) Reference for this request; also the billing correlation id.
`request_uuid`	string (uuid) Use to poll for the result.
`status`	string Enum: `pending`
`result_url`	string (uri) Absolute URL of the poll endpoint for this request.

Standard error responses: 400 401 402 403 429 5XX See common error responses

Previous Person History Next Person Report Result

Request body application/json

{
    "first_name": "John",
    "middle_name": "Andrew",
    "last_name": "Smith",
    "birth_date": "1998-03-21",
    "phones": [
        "+61427151494"
    ],
    "emails": [
        "jsmith1998@example.com"
    ],
    "street_address": "20 Hardy Street",
    "suburb": "Lilydale",
    "state": "VIC",
    "postcode": "3140",
    "candidate_token": "string"
}

Response

200 Request accepted and queued. This response is an acknowledgement only - poll GET /person_report/{request_uuid} for the result, which is documented on that endpoint.

{
    "message": "Ok",
    "function": "person_report",
    "api_reference": "00000000-0000-0000-0000-000000000000",
    "request_uuid": "00000000-0000-0000-0000-000000000000",
    "status": "pending",
    "result_url": "https://example.com"
}

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}