> For the complete documentation index, see [llms.txt](https://manual.personr.co/api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.personr.co/api-documentation/lookups.md).

# Lookups

A Lookup is a one-off check on a person. It isn't linked to an onboarding flow. It runs the same checks as **Lookups** in the dashboard:

* **AML screening**: sanctions, PEP and adverse media.
* **Australian document check**: confirms an Australian identity document's details against the issuing record.

You can run one check or both in a single request. Lookups created through the API appear in the dashboard's Lookups list next to the ones your team creates there.

{% hint style="info" %}
Lookups run in the background. **Create a lookup** returns a `lookupId` straight away with `lookupStatus: "Pending"`. Call **Retrieve a lookup** until `lookupStatus` is `"Reviewed"`. This usually takes a few seconds.
{% endhint %}

## Authentication

Use your workspace API key as a Bearer token, the same as for the other endpoints. A lookup belongs to the workspace that the key belongs to, and only that workspace can retrieve it.

## Create a lookup

`POST https://app.personr.co/api/1.1/wf/api-lookup-create`

### Body parameters

| Parameter       | Type    | Required                        | Description                                                                       |
| --------------- | ------- | ------------------------------- | --------------------------------------------------------------------------------- |
| `aml`           | boolean | One of `aml` or `documentCheck` | Run AML screening                                                                 |
| `documentCheck` | boolean | One of `aml` or `documentCheck` | Run the Australian document check                                                 |
| `documentType`  | string  | When `documentCheck` is `true`  | One of the values in the table below                                              |
| `firstName`     | string  | Yes                             | Given name(s)                                                                     |
| `middleName`    | string  | No                              | Middle name(s)                                                                    |
| `lastName`      | string  | Yes                             | Family name                                                                       |
| `birthDate`     | string  | Yes                             | `YYYY-MM-DD`                                                                      |
| `country`       | string  | No                              | ISO 3166 alpha-3 code (for example `AUS`). Used to narrow AML screening           |
| `displayName`   | string  | No                              | Label shown in the dashboard. Defaults to first and last name                     |
| `singleName`    | string  | No                              | For a person who has only one name, put the name here and leave `firstName` empty |

### Document types and their fields

| `documentType`            | Extra fields                                                                                                      |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `drivers_license`         | `licenceNumber`, `cardNumber`, `stateTerritory` (ACT, NSW, NT, QLD, SA, TAS, VIC, WA)                             |
| `passport`                | `passportNumber`, `gender` (M, F or X)                                                                            |
| `visa`                    | `passportNumber`, `visaCountry` (ISO alpha-3 of the passport country)                                             |
| `medicare_card`           | `medicareNumber`, `medicareIrn`, `cardType` (card colour, as in the dashboard), `expiryDate`                      |
| `immicard`                | `immiCardNumber`                                                                                                  |
| `centrelink_card`         | `centrelinkNumber`, `cardType`, `expiryDate`                                                                      |
| `citizenship_certificate` | `stockNumber`, `acquisitionDate`                                                                                  |
| `descent_certificate`     | `stockNumber`, `acquisitionDate`                                                                                  |
| `birth_certificate`       | `registrationNumber`, `registrationDate`, `certificateNumber`, `stateTerritory`                                   |
| `marriage_certificate`    | `partnerGivenName`, `partnerFamilyName`, `certificateNumber`, `registrationNumber`, `eventDate`, `stateTerritory` |
| `name_change_certificate` | `certificateNumber`, `stateTerritory`                                                                             |

All dates use `YYYY-MM-DD`.

### Example request

```json
{
  "aml": true,
  "documentCheck": true,
  "documentType": "drivers_license",
  "firstName": "Jane",
  "lastName": "Citizen",
  "birthDate": "1990-02-15",
  "country": "AUS",
  "licenceNumber": "123456789",
  "cardNumber": "P1234567",
  "stateTerritory": "NSW"
}
```

### Responses

Errors are returned with HTTP status `200` and `"status": "error"`. Check `status` in the body, not only the HTTP code.

{% tabs %}
{% tab title="Created" %}

```json
{
  "status": "success",
  "response": {
    "lookupId": "1793684000000x123456789012345678",
    "lookupStatus": "Pending"
  }
}
```

{% endtab %}

{% tab title="Error: no check requested" %}

```json
{
  "status": "error",
  "response": "Set aml or documentCheck to true"
}
```

{% endtab %}

{% tab title="Error: invalid document type" %}

```json
{
  "status": "error",
  "response": "Invalid documentType"
}
```

{% endtab %}
{% endtabs %}

## Retrieve a lookup

`GET https://app.personr.co/api/1.1/wf/api-lookup-retrieve?lookupId=<lookupId>`

### Responses

{% tabs %}
{% tab title="Reviewed (AML hit)" %}

```json
{
  "status": "success",
  "response": {
    "lookupId": "1793684000000x123456789012345678",
    "displayName": "Jane Citizen",
    "lookupStatus": "Reviewed",
    "result": "Rejected",
    "sources": ["Anti-Money Laundering"],
    "rejectLabels": ["AML Match Found"],
    "amlMatchCount": 1,
    "amlMatches": ["Jane Citizen"],
    "createdDate": 1793694816592
  }
}
```

{% endtab %}

{% tab title="Pending" %}

```json
{
  "status": "success",
  "response": {
    "lookupId": "1793684000000x123456789012345678",
    "lookupStatus": "Pending"
  }
}
```

{% endtab %}

{% tab title="Error: not found" %}

```json
{
  "status": "error",
  "response": "No lookup found"
}
```

{% endtab %}
{% endtabs %}

### Result fields

| Field                          | Meaning                                                                                       |
| ------------------------------ | --------------------------------------------------------------------------------------------- |
| `lookupStatus`                 | `Pending` while checks run. `Reviewed` once every requested check has finished                |
| `result`                       | `Approved` or `Rejected`                                                                      |
| `sources`                      | One entry per check that ran                                                                  |
| `rejectLabels`                 | Why it was rejected: `Data Mismatch` (the document details didn't match) or `AML Match Found` |
| `amlMatchCount` / `amlMatches` | Number and names of the AML hits. Open the lookup in the dashboard to review each hit         |
| `createdDate`                  | When the lookup was created, in Unix milliseconds                                             |

{% hint style="warning" %}
A lookup that stays `Pending` for more than a few minutes didn't finish. Usually a document field was missing or badly formatted. Check the fields and create a new lookup.
{% endhint %}

## Billing

A lookup created through the API is billed the same way as a Lookup created in the dashboard. Sandbox workspaces aren't billed.

## Sandbox

In a sandbox workspace no provider is contacted. You choose the result with the **last name**:

| Last name contains           | AML screening                                    | Document check                                                     |
| ---------------------------- | ------------------------------------------------ | ------------------------------------------------------------------ |
| anything else                | No hits                                          | Approved                                                           |
| `fail`                       | —                                                | Rejected, `Data Mismatch`                                          |
| `incomplete`                 | —                                                | Rejected, `Data Mismatch` (the document couldn't be fully checked) |
| `error`                      | —                                                | Stays `Pending` (simulates a lookup that didn't finish)            |
| `pep`, `sanction`, `adverse` | One hit of that type, Rejected `AML Match Found` | —                                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://manual.personr.co/api-documentation/lookups.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
