# Phone Contact Lookup

`POST /phone_contact_lookup`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/phone_contact_lookup`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/phone_contact_lookup`

The Phone Contact Lookup API allows you to retrieve the person or persons linked to a specific Australian phone number in the Global Data Universe.

The API requires a phone number to be provided and will return the following data if the phone number is found to be associated with a person in the Global Data Universe:

- First Name
- Middle Name
- Last Name
- Address
- Suburb
- State
- Postcode
- Date the record was last seen

If multiple people are linked to the phone number, the API will return multiple records (up to a maximum of 5).

## Batch processing

The API can accept up to 100 phone numbers per request. Each result will include the phone number in the response and will be returned in the same order as the phone numbers in the request. 

## Sandbox environment data

When processing queries in the sandbox environment, the following records will return a match:

| Phone Number   | First Name | Middle Name | Last Name | Address       | Suburb       | State | Postcode | Date Last Seen |
|:---------------|:-----------|:------------|:----------|:--------------|:-------------|:------|:---------|:---------------|
| +61399999999   | John       | Andrew      | Smith     | 20 Hardy St   | Lilydale     | VIC   | 3140     | 2019-02-20     |
| +61491222111   | John       | Andrew      | Smith     | 20 Hardy St   | Lilydale     | VIC   | 3140     | 2019-02-20     |
| +61491222111   | John       | Andrew      | Smith     | 8 Waltham St  | Richmond     | VIC   | 3121     | 2027-04-01     |
| +61427151494   | Mark       |             | Wood      | PO Box 8144   | Australian National University     | ACT   | 0200     | 2019-07-17     |
| +61491222444   | Mary       | Sally       | Jones     | 35 Yaralla St | Concord West | NSW   | 2138     | 2099-01-01     |
| +61491222333   | Robert     |             | Brown     | 6 Waterview Cl | Port Macquarie | NSW   | 2444     | 2099-07-19     |
| +61880885999   | Marion     |             | Filewood    | 375 Argent St | Broken Hill | NSW   | 2880     | 2002-07-16     |
| +61880885999   | Aaron      | Albert      | Filewood    | 375 Argent St | Broken Hill | NSW   | 2880     | 2002-07-16     |
| +61412024869   | Marion     |             | Filewood    | 375 Argent St | Broken Hill | NSW   | 2880     | 2002-07-16     |

> **Note:** This API returns PII and as such requires an appropriate privacy policy and PII handling processes to be in place.

## Request body

The phone numbers to search for

| Field | Type | Description |
|-------|------|-------------|
| `phones` | array of strings [items 1..32 characters] | The phone numbers to search for in E.164 format. |

**Sample request**

```json
{
    "phones": [
        "+61491222111",
        "+61491222112",
        "+6100000"
    ]
}
```

## Responses

### 200 Result of the check

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful. Example: `Ok` |
| `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` |
| `results` | array of objects | Array of results for each phone number. |
| `results[].phone` | string | The phone number in E.164 format. |
| `results[].message` | string | The result of the search for the phone number. This will be `Ok` if the search was successful (whether it returned a match or not) or an error message if the search could not be completed. For example 'Error: Invalid phone number'. |
| `results[].matches` | array of objects | Array of matched records for the phone number. |
| `results[].matches[].first_name` | string | The first name of the matched individual. |
| `results[].matches[].middle_name` | string or null | The middle name of the matched individual. |
| `results[].matches[].last_name` | string | The last name of the matched individual. |
| `results[].matches[].address` | string | The address of the matched individual. |
| `results[].matches[].suburb` | string | The suburb of the matched individual. |
| `results[].matches[].state` | string | The state of the matched individual. |
| `results[].matches[].postcode` | string | The postcode of the matched individual. |
| `results[].matches[].date_last_seen` | string (date) | The date the address record was last seen in the Global Data Universe |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "results": [
        {
            "phone": "+61491222111",
            "message": "Ok",
            "matches": [
                {
                    "first_name": "John",
                    "middle_name": "Andrew",
                    "last_name": "Smith",
                    "address": "20 HARDY ST",
                    "suburb": "LILYDALE",
                    "state": "VIC",
                    "postcode": "3140",
                    "date_last_seen": "2022-03-15"
                }
            ]
        },
        {
            "phone": "+61491222112",
            "message": "Ok",
            "matches": []
        },
        {
            "phone": "+6100000",
            "message": "Error: Invalid phone number",
            "matches": []
        }
    ]
}
```

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