# Validate with the AEC

`POST /dvs/aec`

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

Validates a name, birthdate and address against the Australian Document Verification Service (DVS) using the Australian Electoral Commission.

## Sandbox environment

When simulating queries in the sandbox environment, a specific set of details will return a
specific result. The response will be determined by the suburb:

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

## Request body

The name, address and birthdate 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 individual Example: `John` |
| `last_name` | string | The last name of the individual Example: `Smith` |
| `birth_date` | string (date) | The date of birth of the individual Example: `1980-01-01` |
| `state` | string | The Australian state of the individual's address Enum: `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS`, `NT`, `ACT` Example: `VIC` |
| `postcode` | string | The postcode of the individual's address Example: `3000` |
| `suburb` | string | The suburb of the individual's address Example: `Melbourne` |
| `street_address` | string | The street address of the individual. Cannot be used in conjunction with street_number, street_name, street_type and flat_unit_number. Example: `The Rialto 5/123 Smith St` |
| `street_number` | string | The street number of the individual's address Example: `123` |
| `street_name` | string | The street name of the individual's address Example: `Smith St` |
| `street_type` | string | The street type of the individual's address Enum: `AC RD`, `ACCESS ROAD`, `ACCESS`, `ALY`, `ALLEY`, `AMBLE`, `APP`, `APPROACH`, `ARC`, `ARCADE`, `ART`, `ARTERIAL ROAD`, `ART LNK`, `ARTERIAL ROAD LINK`, `AVE`, `AVENUE`, `AVE C`, `AVENUE CENTRAL`, `AVE E`, `AVENUE EAST`, `AVE EXT`, `AVENUE EXTENSION`, `AVE N`, `AVENUE NORTH`, `AVE S`, `AVENUE SOUTH`, `AVE W`, `AVENUE WEST`, `BANK`, `BAY`, `BCH`, `BEACH`, `BEND`, `BLVD`, `BOULEVARDE`, `BLVD E`, `BOULEVARDE EAST`, `BLVD N`, `BOULEVARDE NORTH`, `BLVD S`, `BOULEVARDE SOUTH`, `BLVD W`, `BOULEVARDE WEST`, `BRACE`, `BRAE`, `BRDWLK`, `BOARDWALK`, `BRDWY`, `BROADWAY`, `BRETT`, `BRK`, `BREAK`, `BROW`, `BULL`, `BWL`, `BOWL`, `BYPS`, `BYPASS`, `BYWAY`, `CRES N`, `CRESCENT NORTH`, `CRES S`, `CRESCENT SOUTH`, `CRES W`, `CRESCENT WEST`, `CREST`, `CRIEF`, `CRS`, `CROSS`, `CRS W`, `CROSS WEST`, `CRSNG`, `CROSSING`, `CT`, `COURT`, `CT E`, `COURT EAST`, `CT N`, `COURT NORTH`, `CT S`, `COURT SOUTH`, `CT W`, `COURT WEST`, `CTS`, `COURTS`, `CTYD`, `COURTYARD`, `CUT`, `CUTTING`, `DALE`, `DELL`, `DENE`, `DEV`, `DEVIATION`, `DEV RD`, `DEVIATION ROAD`, `DIST`, `DISTRIBUTOR`, `DIVDE`, `DIVIDE`, `DOCK`, `DOMAIN`, `DOWNS`, `DR`, `DRIVE`, `DR E`, `DRIVE EAST`, `DR EXT`, `DRIVE EXTENDED`, `DR N`, `DRIVE NORTH`, `DR S`, `DRIVE SOUTH`, `DR W`, `DRIVE WEST`, `EDGE`, `ELBOW`, `END`, `ENT`, `ENTRANCE`, `ESMNT`, `EASEMENT`, `ESP`, `ESPLANADE`, `ESP E`, `ESPLANADE EAST`, `ESP N`, `ESPLANADE NORTH`, `ESP S`, `ESPLANADE SOUTH`, `CAUS`, `CAUSEWAY`, `CHASE`, `CIR`, `CIRCLE`, `CIR E`, `CIRCLE EAST`, `CIR N`, `CIRCLE NORTH`, `CIR S`, `CIRCLE SOUTH`, `CIR W`, `CIRCLE WEST`, `CL`, `CLOSE`, `CL E`, `CLOSE EAST`, `CL N`, `CLOSE NORTH`, `CL S`, `CLOSE SOUTH`, `CL W`, `CLOSE WEST`, `CLSTR`, `CLUSTER`, `CMMN`, `COMMON`, `CMMNS`, `COMMONS`, `CNCRSE`, `CONCOURSE`, `CNR`, `CORNER`, `CNTR`, `CENTRE`, `CORSO`, `COURSE`, `COVE`, `CPS`, `COPSE`, `CRCLT`, `CIRCLET`, `CRCS`, `CIRCUS`, `CRCS E`, `CIRCUS EAST`, `CRCS N`, `CIRCUS NORTH`, `CRCS S`, `CIRCUS SOUTH`, `CRCS W`, `CIRCUS WEST`, `CRCT`, `CIRCUIT`, `CRCT E`, `CIRCUIT EAST`, `CRCT N`, `CIRCUIT NORTH`, `CRCT S`, `CIRCUIT SOUTH`, `CRCT W`, `CIRCUIT WEST`, `CRES`, `CRESCENT`, `CRES E`, `CRESCENT EAST`, `ESP W`, `ESPLANADE WEST`, `EST`, `ESTATE`, `EXPWY`, `EXPRESSWAY`, `FAWY`, `FAIRWAY`, `FLAT`, `FOLW`, `FOLLOW`, `FORD`, `FR`, `FRONTAGE`, `FWY`, `FREEWAY`, `GAP`, `GATE`, `GATEWAY`, `GDN`, `GARDEN`, `GDNS`, `GARDENS`, `GLADE`, `GLEN`, `GLY`, `GULLY`, `GR`, `GROVE`, `GR E`, `GROVE EAST`, `GR N`, `GROVE NORTH`, `GR S`, `GROVE SOUTH`, `GR W`, `GROVE WEST`, `GRANGE`, `GREEN`, `HAVEN`, `HDWY`, `HIDEAWAY`, `HILL`, `HLLW`, `HOLLOW`, `HRBR`, `HARBOUR`, `HTH`, `HEATH`, `HTS`, `HEIGHTS`, `HWY`, `HIGHWAY`, `HWY E`, `HIGHWAY EAST`, `HWY N`, `HIGHWAY NORTH`, `HWY S`, `HIGHWAY SOUTH`, `HWY W`, `HIGHWAY WEST`, `INLET`, `IS`, `ISLAND`, `JN`, `JUNCTION`, `KEY`, `KEYS`, `KNOLL`, `LA`, `LANE`, `LA E`, `LANE EAST`, `LA N`, `LANE NORTH`, `LA S`, `LANE SOUTH`, `LA W`, `LANE WEST`, `LINE`, `LINK`, `LKT`, `LOOKOUT`, `LNDG`, `LANDING`, `LOOP`, `MALL`, `MART`, `MEAD`, `MEW`, `MEWS`, `MNDR`, `MEANDER`, `MTRWY`, `MOTORWAY`, `NOOK`, `OUTLK`, `OUTLOOK`, `OUTLT`, `OUTLET`, `OVAL`, `OVRPS`, `OVERPASS`, `PASS`, `PDE`, `PARADE`, `PDE E`, `PARADE EAST`, `PDE N`, `PARADE NORTH`, `PDE S`, `PARADE SOUTH`, `PDE W`, `PARADE WEST`, `PK`, `PARK`, `PK E`, `PARK EAST`, `PK N`, `PARK NORTH`, `PK S`, `PARK SOUTH`, `PK W`, `PARK WEST`, `PKT`, `POCKET`, `PKWY`, `PARKWAY`, `PL`, `PLACE`, `PL E`, `PLACE EAST`, `PL N`, `PLACE NORTH`, `PL S`, `PLACE SOUTH`, `PL W`, `PLACE WEST`, `PLAZA`, `PNSLA`, `PENINSULA`, `PORT`, `PREC`, `PRECINCT`, `PRMNDE`, `PROMENADE`, `PSGE`, `PASSAGE`, `PT`, `POINT`, `PTH`, `PATH`, `PTHWY`, `PATHWAY`, `PUR`, `PURSUIT`, `QDRNT`, `QUADRANT`, `QUAY`, `QUAY E`, `QUAY EAST`, `QUAY N`, `QUAY NORTH`, `QUAY S`, `QUAY SOUTH`, `QUAY W`, `QUAY WEST`, `QUAYS`, `RAMBLE`, `RCH`, `REACH`, `RD`, `ROAD`, `RD C`, `ROAD CENTRAL`, `RD E`, `ROAD EAST`, `RD EXT`, `ROAD EXTENDED`, `RD N`, `ROAD NORTH`, `RD S`, `ROAD SOUTH`, `RD SE`, `ROAD SOUTH EAST`, `RD W`, `ROAD WEST`, `RDS`, `ROADS`, `RDWY`, `ROADWAY`, `RESERVE`, `REST`, `RIDE`, `RIDGE`, `RING`, `RISE`, `RND`, `ROUND`, `RNGE`, `RANGE`, `ROUTE`, `ROUTE N`, `ROUTE S`, `ROW`, `ROW S`, `ROW SOUTH`, `ROWE`, `RTRT`, `RETREAT`, `RTRY`, `ROTARY`, `RUN`, `SBWY`, `SUBWAY`, `SD`, `STRAND`, `SKYLINE`, `SLOPE`, `SPUR`, `SQ`, `SQUARE`, `SQ E`, `SQUARE EAST`, `SQ N`, `SQUARE NORTH`, `SQ S`, `SQUARE SOUTH`, `SQ W`, `SQUARE WEST`, `ST`, `STREET`, `ST C`, `STREET CENTRAL`, `ST E`, `STREET EAST`, `ST EXT`, `STREET EXTENDED`, `ST MALL`, `STREET MALL`, `ST N`, `STREET NORTH`, `ST S`, `STREET SOUTH`, `ST W`, `STREET WEST`, `STAIRS`, `STEPS`, `STRGHT`, `STRAIGHT`, `STRIP`, `STRT`, `STRAIT`, `TARN`, `TCE`, `TERRACE`, `TCE E`, `TERRACE EAST`, `TCE N`, `TERRACE NORTH`, `TCE S`, `TERRACE SOUTH`, `TCE W`, `TERRACE WEST`, `THRWY`, `THROUGHWAY`, `TLWY`, `TOLLWAY`, `TOP`, `TOR`, `TOUR`, `TOURIST ROAD`, `TRACK`, `TRACK E`, `TRACK EAST`, `TRACK N`, `TRACK NORTH`, `TRACK S`, `TRACK SOUTH`, `TRACK W`, `TRACK WEST`, `TRAIL`, `TURN`, `VALE`, `VALE N`, `VALE NORTH`, `VALE S`, `VALE SOUTH`, `VIEW`, `VIEWS`, `VILLA`, `VISTA`, `VLY`, `VALLEY`, `VUE`, `WALK`, `WALK E`, `WALK EAST`, `WALK N`, `WALK NORTH`, `WALK S`, `WALK SOUTH`, `WALK W`, `WALK WEST`, `WATERS`, `WAY`, `WAY E`, `WAY EAST`, `WAY N`, `WAY NORTH`, `WAY S`, `WAY SOUTH`, `WAY W`, `WAY WEST`, `WAYS`, `WEG`, `WLKWY`, `WALKWAY`, `WYND` Example: `ST` |
| `flat_unit_number` | string | The flat or unit number of the individual's address Example: `5` |
| `habitation_building_name` | string | The building name of the individual's address Example: `The Rialto` |

**Sample request**

```json
{
    "preflight": false,
    "consent": true,
    "first_name": "John",
    "last_name": "Smith",
    "birth_date": "1980-01-01",
    "state": "VIC",
    "postcode": "3000",
    "suburb": "Melbourne",
    "street_address": "The Rialto 5/123 Smith St",
    "street_number": "123",
    "street_name": "Smith St",
    "street_type": "ST",
    "flat_unit_number": "5",
    "habitation_building_name": "The Rialto"
}
```

## 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_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` | object | The check data |
| `data.response_type` | string | The type of response Example: `AECResponse` |
| `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: `Address not known or invalid.` |
| `data.additional_information[].code` | string | A code number associated with the corresponding message. Example: `EC-001` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "dvs_aec",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "data": {
        "response_type": "AECResponse",
        "activity_id": "sandbox-d06ed58a-b279-4f50-9b6e-5a0a26b4e87d",
        "verification_request_number": "dec306ed-7cff-41c0-b02f-889e430f5309",
        "verification_result_code": "N",
        "additional_information": [
            {
                "message": "Address not known or invalid.",
                "code": "EC-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))