# Person Report Result

`GET /person_report/{uuid}`

- Live: `GET https://gdapi.globaldata.net.au/api/v2/person_report/{uuid}`
- Sandbox: `GET https://sandbox-gdapi.globaldata.net.au/api/v2/person_report/{uuid}`

## Experimental

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

Polls for the result of a Person Report request. Free of charge - only the originating
`POST /person_report` is billed (and, for accounts billed on success, only when the outcome is
`resolved`).

Poll until `status` is `complete` or `error`. Typical turnaround is a few seconds; allow up to a
minute when court and social sections are included. Results are retained for 24 hours.

| `status` | Meaning |
|:--|:--|
| `pending` | Queued, not yet started. |
| `processing` | Running; `status_message` describes the current step. |
| `complete` | Finished - the body carries `resolution` and, when resolved, `report` and `provenance`. |
| `error` | The report could not be produced; `status_message` explains. Nothing is billed. |

When `complete`, the body is the full report response described on `POST /person_report`:
`resolution.outcome` (`resolved | low_confidence | ambiguous | too_many | not_found`), `report`
(resolved only), and `provenance` (sources, inferences, research notes). `request_reference` is
the `api_reference` of the originating request - the billing correlation id.

## PDF

Append `?pdf=true` to receive the completed report as a formatted PDF (`application/pdf`) instead of
JSON - the resolution summary, every section, and the research notes, inferences and sources as an
appendix. While the request is still `pending` or `processing` the JSON status is returned regardless.
Candidate tokens are only available in the JSON form.

## Sandbox

The sandbox queue runs synchronously, so the result is normally `complete` on the first poll.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `uuid` | path | string (uuid) | **Required.** The `request_uuid` returned by `POST /person_report`. |
| `pdf` | query | boolean | When `true`, return the completed report as a PDF document instead of JSON. Default: `false` |

## Responses

### 200 Current state of the request and, when complete, the report (JSON by default, or a PDF when `pdf=true`).

Content type: `application/json`, `application/pdf`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Example: `Ok` |
| `api_reference` | string (uuid) | Reference for this poll call. |
| `request_uuid` | string (uuid) |  |
| `request_reference` | string (uuid) | The `api_reference` of the originating request (billing correlation id). |
| `status` | string | Enum: `pending`, `processing`, `complete`, `error` |
| `status_message` | string or null |  |
| `search_criteria` | object | Present when `status` is `complete`. Echo of the supplied identifiers, normalised as searched. Fields not supplied are omitted. |
| `resolution` | object | Present when `status` is `complete`. |
| `resolution.outcome` | string | Enum: `resolved`, `low_confidence`, `ambiguous`, `too_many`, `not_found` |
| `resolution.confidence` | string | Enum: `high`, `medium`, `low` |
| `resolution.candidate_count` | integer |  |
| `resolution.rounds` | integer |  |
| `resolution.input_matches` | object (dynamic) | Per-field comparison of the supplied details with the resolved subject. |
| `resolution.corroborations` | array of strings |  |
| `resolution.flags` | array of strings |  |
| `resolution.candidates` | array of objects | Redacted candidates (`ambiguous` / `low_confidence` only). |
| `resolution.candidates[].candidate_token` | string | Re-submit this to `POST /person_report` to select the candidate. Valid for one hour, same environment only. |
| `resolution.candidates[].name` | string |  |
| `resolution.candidates[].name_variants` | array of strings |  |
| `resolution.candidates[].birth_year` | integer or null |  |
| `resolution.candidates[].localities` | array of strings |  |
| `resolution.candidates[].tenure` | array of integers | First and last year the candidate is seen. |
| `resolution.candidates[].score` | integer |  |
| `resolution.candidates[].confidence` | string | Enum: `high`, `medium`, `low` |
| `resolution.candidates[].evidence_for` | array of strings |  |
| `resolution.candidates[].evidence_against` | array of strings |  |
| `resolution.hints` | object | Narrowing hints (`too_many` / `ambiguous` / `not_found`). |
| `resolution.hints.suggested_fields` | array of strings |  |
| `resolution.hints.by_state` | object (dynamic) |  |
| `resolution.hints.by_birth_decade` | object (dynamic) |  |
| `report` | object | Present when `status` is `complete` and `resolution.outcome` is `resolved`. |
| `report.identity` | object |  |
| `report.identity.first_name` | string |  |
| `report.identity.middle_name` | string or null |  |
| `report.identity.last_name` | string |  |
| `report.identity.name_variants` | array of strings |  |
| `report.identity.gender` | string or null |  |
| `report.identity.birth_date` | string (date) or null |  |
| `report.identity.birth_date_source` | string or null | Example: `asic+global_data` |
| `report.identity.birth_date_candidates` | array of objects | Every date of birth seen, with its supporting votes. |
| `report.identity.birth_date_input_match` | string | Enum: `match`, `near_miss`, `same_year`, `no_match`, `no_data`, `not_provided` |
| `report.identity.age` | integer or null |  |
| `report.identity.deceased` | boolean |  |
| `report.identity.first_seen` | string or null |  |
| `report.identity.last_seen` | string or null |  |
| `report.identity.record_count` | integer |  |
| `report.identity.asic_record_count` | integer |  |
| `report.identity.flags` | array of strings |  |
| `report.identity.sources` | array of strings |  |
| `report.addresses` | object | Address timeline. Each record carries the address, the subject's tenure, occupancy, `co_residents` (with dates of birth, tenure and overlap) and real-estate `listings`. |
| `report.contacts` | object | Phones (with type and carrier) and emails, each with the dates seen and whether it matched a supplied identifier. |
| `report.household` | object |  |
| `report.household.status` | string |  |
| `report.household.possible_relatives` | array of objects |  |
| `report.household.possible_relatives[].name` | string |  |
| `report.household.possible_relatives[].birth_date` | string (date) or null |  |
| `report.household.possible_relatives[].address` | string or null |  |
| `report.household.possible_relatives[].basis` | string | Why this person is suggested - co-resident with the same surname, or a rare-surname match graded by proximity. |
| `report.judgements` | object |  |
| `report.business` | object | ABN links verified by locality, plus unverified associated businesses. |
| `report.asic` | object |  |
| `report.asic.asic_record` | string | Enum: `found`, `not_found`, `indeterminate` |
| `report.asic.record_type` | string |  |
| `report.asic.record_count` | integer |  |
| `report.asic.linked_record_count` | integer |  |
| `report.asic.place_of_birth` | object or null |  |
| `report.asic.dob_variants` | array of strings | Dates of birth on ASIC records that differ from the confirmed date (data-entry variants). |
| `report.asic.summary` | string |  |
| `report.watchlists` | object |  |
| `report.watchlists.pep_sanctions` | object |  |
| `report.watchlists.pep_sanctions.status` | string | Enum: `clear`, `matches`, `error` |
| `report.watchlists.pep_sanctions.matches` | array of objects |  |
| `report.watchlists.banned_disqualified` | object |  |
| `report.watchlists.banned_disqualified.status` | string | Enum: `clear`, `matches`, `error` |
| `report.watchlists.banned_disqualified.matches` | array of objects |  |
| `report.court` | object |  |
| `report.court.status` | string | Enum: `clear`, `matches`, `error`, `skipped` |
| `report.court.search_name` | string |  |
| `report.court.total_records_available` | integer |  |
| `report.court.by_listing` | object (dynamic) |  |
| `report.court.summaries` | array of objects |  |
| `report.court.summaries[].name_on_record` | string |  |
| `report.court.summaries[].listing` | string | Enum: `criminal`, `civil` |
| `report.court.summaries[].record_count` | integer |  |
| `report.court.summaries[].state` | string or null |  |
| `report.court.summaries[].verified_subject` | boolean | Example: `false` |
| `report.social` | object | Professional profile matched on one of the subject's phones or emails and carrying the subject's name. |
| `report.section_status` | object (dynamic) |  |
| `provenance` | object | Present when `status` is `complete`. |
| `provenance.sources` | array of objects | Every lookup performed, with the exact query, dataset or provider, round and result count. |
| `provenance.inferences` | array of objects | Every conclusion drawn, with the rule applied and the evidence it rests on. |
| `provenance.research_notes` | one of 2 shapes | One of: array; string. Chronological research log (array of entries, or a single string in `summary` mode). string: string |
| `provenance.research_notes (array)[].seq` | integer |  |
| `provenance.research_notes (array)[].round` | integer |  |
| `provenance.research_notes (array)[].phase` | string | Enum: `input`, `lookup`, `finding`, `decision`, `rejected`, `not_attempted`, `outcome` |
| `provenance.research_notes (array)[].text` | string |  |
| `provenance.research_notes (array)[].refs` | array of strings |  |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "00000000-0000-0000-0000-000000000000",
    "request_uuid": "00000000-0000-0000-0000-000000000000",
    "request_reference": "00000000-0000-0000-0000-000000000000",
    "status": "pending",
    "status_message": "string",
    "resolution": {
        "outcome": "resolved",
        "confidence": "high",
        "candidate_count": 0,
        "rounds": 0,
        "corroborations": [
            "string"
        ],
        "flags": [
            "string"
        ],
        "candidates": [
            {
                "candidate_token": "string",
                "name": "string",
                "name_variants": [
                    "string"
                ],
                "birth_year": 0,
                "localities": [
                    "string"
                ],
                "tenure": [
                    0
                ],
                "score": 0,
                "confidence": "high",
                "evidence_for": [
                    "string"
                ],
                "evidence_against": [
                    "string"
                ]
            }
        ],
        "hints": {
            "suggested_fields": [
                "string"
            ]
        }
    },
    "report": {
        "identity": {
            "first_name": "string",
            "middle_name": "string",
            "last_name": "string",
            "name_variants": [
                "string"
            ],
            "gender": "string",
            "birth_date": "2024-01-01",
            "birth_date_source": "asic+global_data",
            "birth_date_candidates": [],
            "birth_date_input_match": "match",
            "age": 0,
            "deceased": true,
            "first_seen": "string",
            "last_seen": "string",
            "record_count": 0,
            "asic_record_count": 0,
            "flags": [
                "string"
            ],
            "sources": [
                "string"
            ]
        },
        "household": {
            "status": "string",
            "possible_relatives": [
                {
                    "name": "string",
                    "birth_date": "2024-01-01",
                    "address": "string",
                    "basis": "string"
                }
            ]
        },
        "asic": {
            "asic_record": "found",
            "record_type": "string",
            "record_count": 0,
            "linked_record_count": 0,
            "place_of_birth": null,
            "dob_variants": [
                "string"
            ],
            "summary": "string"
        },
        "watchlists": {
            "pep_sanctions": {
                "status": "clear",
                "matches": []
            },
            "banned_disqualified": {
                "status": "clear",
                "matches": []
            }
        },
        "court": {
            "status": "clear",
            "search_name": "string",
            "total_records_available": 0,
            "summaries": [
                {
                    "name_on_record": "string",
                    "listing": "criminal",
                    "record_count": 0,
                    "state": "string",
                    "verified_subject": false
                }
            ]
        }
    },
    "provenance": {
        "sources": [],
        "inferences": [],
        "research_notes": [
            {
                "seq": 0,
                "round": 0,
                "phase": "input",
                "text": "string",
                "refs": [
                    "string"
                ]
            }
        ]
    }
}
```

Also available as a PDF (application/pdf)

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