# Phone Contact Validate

`POST /phone_contact_validate`

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

The Phone Contact Validate API allows you to validate the link between a specific Australian phone number and a person associated with that phone number in the Global Data Universe.

The API requires a phone number and persons details to be provided and will return a match if the phone number is found to be associated with that person in the Global Data Universe. If no match is found, the API will return a `no_match` result. If the phone number is not a valid Australian phone number or could not be searched, the API will return an `error` result.

Request Parameters:
- Phone Number
- First Name
- Middle Name
- Last Name

## Batch processing

The API can accept up to 100 requests per call. The response will include the results for each request in the same order as the requests were made.

## Sandbox environment data

When processing queries in the sandbox environment, the following records are available:

| 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     |

## Name match results

Before the matching process, names are standardised for comparison and any aliases are resolved.

The `first_name_match` and `last_name_match` properties will return with one of the `exact`, `partial`, `alias` or `no_match` values. The `last_name_match` property will return with one of the `exact` or `no_match` values.

| Name Match Result | Description |
|:------------------|:------------|
| `exact`           | An exact match was found for the name. This is the best match result and will be returned if the name is an exact match for the name in the record. |
| `partial`         | A partial substring match was found for the name. This will be returned if the name is a substring match starting with the name in the record. For example, if the name in the record is "Johnathan" and the name in the request is "John" or "J", the match result will be `partial`. |
| `alias`           | An alias match was found for the name. This will be returned if the name is an alias match for the name in the record. For example, if the name in the record is "William" and the name in the request is "Bill" or "Willy", the match result will be `alias`. |
| `no_match`        | No match was found for the name. |

Note: a last name must match exactly for a match to be returned.

The returned `result` parameter will be determined by the following rules:
- If all of the name match results are `exact`, then the result will be `match`.
- If all of the name match results are `no_match`, then the result will be `no_match`.
- If any of the name match results are `partial` or `alias`, then the result will be `possible_match`.

## Request body

The phone number and persons details to validate

| Field | Type | Description |
|-------|------|-------------|
| `requests` | array of objects | The list of requests to make. |
| `requests[].phone` | string | The phone number to validate in E.164 format. |
| `requests[].first_name` | string | The first name of the person to validate. |
| `requests[].middle_name` | string or null | The optional middle name of the person to validate. |
| `requests[].last_name` | string | The last name of the person to validate. |

**Sample request**

```json
{
    "requests": [
        {
            "phone": "+61491222111",
            "first_name": "Johnny",
            "middle_name": "A",
            "last_name": "Smith"
        },
        {
            "phone": "+61491222444",
            "first_name": "Paul",
            "middle_name": null,
            "last_name": "Smitherton"
        }
    ]
}
```

## Responses

### 200 Successful response

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 | A list of results for each of the requests made. |
| `results[].phone` | string | The phone number from the request in E.164 format. |
| `results[].result` | string | The result of the match check for the phone number in the request. - `match`: An exact match was found for the named person. - `no_match`: No match was found for the named person. - `possible_match`: A possible match is returned when the `first_name`, or `middle_name` properties had a partial or alias match. - `error`: The request was skipped because the phone number is not a valid Australian phone number or could not be searched. Enum: `match`, `no_match`, `possible_match`, `error` |
| `results[].message` | string | A message indicating the result of the request. This will be `Ok` if the request was successful or an error message if the request could not be completed. For example `Error: Invalid phone number`. |
| `results[].first_name_match` | string or null | The result of the match check for the first name. This will be null if the match_result is `error`. - `exact`: An exact match was found for the first name. - `partial`: A partial substring match was found for the first name. - `alias`: An alias match was found for the first name. - `no_match`: No match was found for the first name. Enum: `exact`, `partial`, `alias`, `no_match` |
| `results[].middle_name_match` | string or null | The result of the match check for the middle name. This will be null if the match_result is `error` or if the middle name was not provided in the request. - `exact`: An exact match was found for the middle name. - `partial`: A partial substring match was found for the middle name. - `alias`: An alias match was found for the middle name. - `no_match`: No match was found for the middle name. Enum: `exact`, `partial`, `alias`, `no_match` |
| `results[].last_name_match` | string or null | The result of the match check for the last name. This will be null if the match_result is `error`. Enum: `exact`, `no_match` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "results": [
        {
            "phone": "+61491222111",
            "result": "possible_match",
            "message": "Ok",
            "first_name_match": "alias",
            "middle_name_match": "partial",
            "last_name_match": "exact"
        },
        {
            "phone": "+61491222444",
            "result": "no_match",
            "message": "Ok",
            "first_name_match": "no_match",
            "middle_name_match": "no_match",
            "last_name_match": "no_match"
        }
    ]
}
```

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