# Validate a change of name certificate

`POST /dvs/name_change`

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

Validates a change of name certificate against the Australian Document Verification Service (DVS).

## Sandbox environment

When simulating queries in the sandbox environment, a specific set of change of name 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-change-of-name-certificate)

## Request body

The change of name 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 new first name of the document holder Example: `John` |
| `last_name` | string | The new 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 change of name 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_name_change_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: `ChangeOfNameCertificateResponse` |
| `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: `Registration number does not match.` |
| `data.additional_information[].code` | string | A code number associated with the corresponding message. Example: `NC-001` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "dvs_name_change_cert",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": {
        "response_type": "ChangeOfNameCertificateResponse",
        "activity_id": "sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d",
        "verification_request_number": "dec306ed-7cff-41c0-b02f-889e430f5309",
        "verification_result_code": "N",
        "additional_information": [
            {
                "message": "Registration number does not match.",
                "code": "NC-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))