# Validate a birth certificate

`POST /dvs/birth_cert`

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

Validates a birth certificate against the Australian Document Verification Service (DVS).

## Sandbox environment

When simulating queries in the sandbox environment, a specific set of birth certificates will return a
specific result. The response will be determined by the certificate number:

[DVS sandbox responses for this document](/docs/guides/dvs/sandbox-responses#dvs-birth-certificate)

## Verification notes

* For ACT, NSW, NT, SA, VIC, WA: Either a Registration Number or Certificate Number must be provided. If both numbers are provided both will be checked.
* For QLD and TAS: Either a Registration Date or Certificate Number must be provided. If both are provided both will be checked. A Registration Number is not required.

> All states recommend that the Certificate Number is used for verification where possible as this is more reliable than the Registration Number or Registration Date. If a birth certificate fails to verify using the Registration Number or Registration Date, it is recommended to try again using the Certificate Number.

## Certificate Number and private sector callers

Private sector DVS users, which includes all Global Data API customers, **must** supply the
Certificate Number for NT, SA and ACT certificates issued on or after the following dates:

| State | Certificate Number required for certificates issued from |
|---|---|
| NT | 12 July 1999 |
| SA | 1 November 1999 |
| ACT | 1 May 2002 |

This is a DVS rule rather than an API validation rule, and it is deliberately not enforced here.
The validation above accepts either number, because a certificate issued before these dates does
not carry a Certificate Number at all and must still be able to verify on its Registration Number.

The consequence is that a request can pass validation and still come back unverified. If you are
checking an NT, SA or ACT certificate issued on or after the date above and you do not send
`certificate_number`, expect a `D` result (no match on the data supplied) rather than a
validation error.

## Request body

The birth certificate details to validate

| Field | Type | Description |
|-------|------|-------------|
| `preflight` | boolean | When set to true, the request will only perform a preflight check to validate the input parameters. No actual verification will be performed. Example: `false` |
| `consent` | boolean | The individual's consent to perform the check Example: `true` |
| `first_name` | string | The first name of the document holder Example: `John` |
| `last_name` | string | The last name of the document holder Example: `Smith` |
| `birth_date` | string (date) | The date of birth of the document holder Example: `1980-01-01` |
| `registration_number` | string | The registration number on the certificate to be validated Example: `1234567` |
| `certificate_number` | string | The certificate number on the certificate to be validated Example: `123456789` |
| `registration_date` | string (date) | The registration date on the certificate to be validated (only relevant for QLD or TAS) Example: `2021-02-28` |
| `state` | string | The state of issue for the birth certificate Enum: `NSW`, `VIC`, `QLD`, `TAS`, `ACT`, `NT`, `SA`, `WA` Example: `VIC` |

**Sample request**

```json
{
    "preflight": false,
    "consent": true,
    "first_name": "John",
    "last_name": "Smith",
    "birth_date": "1980-01-01",
    "registration_number": "1234567",
    "certificate_number": "123456789",
    "registration_date": "2021-02-28",
    "state": "VIC"
}
```

## Responses

### 200 Result of the document verification 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` |
| `function` | string | The function that was called Example: `dvs_birth_cert` |
| `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` |
| `data` | object | The check data |
| `data.response_type` | string | The type of response Example: `BirthCertificateResponse` |
| `data.activity_id` | string | A reference ID for this activity. This ID can be used to track the activity in the logs. Example: `sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d` |
| `data.verification_request_number` | string | A unique reference number for this request Example: `dec306ed-7cff-41c0-b02f-889e430f5309` |
| `data.verification_result_code` | string | The result of the verification * `Y` - The document is valid * `N` - The document was not matched * `D` - The document is invalid or not electronically captured * `S` - An error occurred during the check Enum: `Y`, `N`, `S`, `D` Example: `N` |
| `data.additional_information` | array of objects | An array of expanded responses returned from the DVSHub or Document Issuer for N or D results |
| `data.additional_information[].message` | string | A message indicating the reason for the N or D result. Example: `Family Name does not match.` |
| `data.additional_information[].code` | string | A code number associated with the corresponding message. Example: `BC-001` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "dvs_birth_cert",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": {
        "response_type": "BirthCertificateResponse",
        "activity_id": "sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d",
        "verification_request_number": "dec306ed-7cff-41c0-b02f-889e430f5309",
        "verification_result_code": "N",
        "additional_information": [
            {
                "message": "Family Name does not match.",
                "code": "BC-001"
            }
        ]
    }
}
```

### 202 A successful preflight check. A 400 will be returned if the preflight check fails.

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` |
| `function` | string | The function that was called Example: `dvs_aec` |
| `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` |
| `data` | null | For preflight checks this is null |

**Sample response**

```json
{
    "message": "Ok",
    "function": "dvs_aec",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": null
}
```

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