# Payroll and Super Check

`POST /payroll_super_check`

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

Validates a person's details against payroll and/or superannuation records.

## Minimum search requirements

In order to perform a valid lookup, a minimum of the following fields are required:
  - first_name
  - last_name
  - birth_date
  - either super_consent or payroll_consent

The response will indicate if the provided fields are either `MATCHED` or `UNMATCHED` against the records.

## Sandbox environment

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

| First Name | Middle Name | Last Name | Birth Date | Address                             | Email             | Telephone  | Employer ABN | Match Source |
|:-----------|:------------|:----------|:-----------|:------------------------------------|:------------------|:-----------|:------------:|:------------:|
| John       | James       | Doe       | 1990-01-01 | 4/123 Fake St, Fakeville Vic 3987   | john@example.com  | 0400123456 | 12345678901  | Super and Payroll |
| Jane       | Karen       | Smith     | 1995-02-18 | 456 Wrong Ave, Sampleville NSW 2785 | jane@example.com  | 0412345678 | 98765432109  | Payroll |
| Fiona      |             | Cheng     | 1982-06-28 | 3 Right Ave, Hiddenville WA 6824    | fiona@example.com | 0400987654 | 91237856482  | Super |

> Note: If the first name is `service` and the last name is `unavailable`, the match will return a 503 error - Third Party Unavailable.

## Request body

The details of the person to validate

| Field | Type | Description |
|-------|------|-------------|
| `first_name` | string | The first name of the individual Example: `John` |
| `middle_name` | string | The middle name of the individual Example: `James` |
| `last_name` | string | The last name of the individual Example: `Doe` |
| `birth_date` | string (date) | The date of birth of the individual Example: `1990-01-01` |
| `address` | object | The address of the individual |
| `address.street_address` | string | The street line of the address Example: `4/123 Fake Street` |
| `address.suburb` | string | The suburb of the address Example: `Fakeville` |
| `address.state` | string | The state of the address Enum: `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS`, `NT`, `ACT` Example: `VIC` |
| `address.postcode` | string | The postcode of the address Example: `3987` |
| `email` | string | The email address of the individual Example: `john@example.com` |
| `phone` | string | The phone number of the individual in 0NSN format Example: `0400123456` |
| `employer_abn` | string | The ABN of the employer Example: `12345678901` |
| `super_consent` | boolean | The individual's consent to search superannuation records Example: `true` |
| `payroll_consent` | boolean | The individual's consent to search payroll records Example: `true` |

**Sample request**

```json
{
    "first_name": "John",
    "middle_name": "James",
    "last_name": "Doe",
    "birth_date": "1990-01-01",
    "address": {
        "street_address": "4/123 Fake Street",
        "suburb": "Fakeville",
        "state": "VIC",
        "postcode": "3987"
    },
    "email": "john@example.com",
    "phone": "0400123456",
    "employer_abn": "12345678901",
    "super_consent": true,
    "payroll_consent": true
}
```

## Responses

### 200 Result of the validation 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` |
| `super` | object | The result of the superannuation check |
| `super.person` | string | The result of matching the first name, last name and birth date. Enum: `MATCHED`, `UNMATCHED` Example: `MATCHED` |
| `super.middle_name` | string | The result of matching the middle name Enum: `MATCHED`, `UNMATCHED` Example: `MATCHED` |
| `super.address` | string | The result of matching the address Enum: `MATCHED`, `UNMATCHED` Example: `MATCHED` |
| `super.email` | string | The result of matching the email Enum: `MATCHED`, `UNMATCHED` Example: `MATCHED` |
| `super.phone` | string | The result of matching the phone number Enum: `MATCHED`, `UNMATCHED` Example: `MATCHED` |
| `super.employer_abn` | string | The result of matching the employer ABN Enum: `MATCHED`, `UNMATCHED` Example: `MATCHED` |
| `payroll` | object | The result of the payroll check |
| `payroll.person` | string | The result of matching the first name, last name and dob. Example: `MATCHED` |
| `payroll.middle_name` | string | The result of matching the middle name Example: `MATCHED` |
| `payroll.address` | string | The result of matching the address Example: `MATCHED` |
| `payroll.email` | string | The result of matching the email Example: `MATCHED` |
| `payroll.telephone` | string | The result of matching the telephone number Example: `MATCHED` |
| `payroll.employer_abn` | string | The result of matching the employer ABN Example: `MATCHED` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "super": {
        "person": "MATCHED",
        "middle_name": "MATCHED",
        "address": "MATCHED",
        "email": "MATCHED",
        "phone": "MATCHED",
        "employer_abn": "MATCHED"
    },
    "payroll": {
        "person": "MATCHED",
        "middle_name": "MATCHED",
        "address": "MATCHED",
        "email": "MATCHED",
        "telephone": "MATCHED",
        "employer_abn": "MATCHED"
    }
}
```

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