# Address Validate Bulk

`POST /address_validate_bulk`

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

Bulk variant of Address Validate. This endpoint accepts up to **200** address validation requests in a single call.

Each item in the `requests` array uses the same validation rules and fields as `address_validate`:

- `street_address` plus at least one of `suburb` or `postcode`
- `street_address` plus `suburb_state_postcode`
- `full_address`

If `check_id` is provided per request, it will be echoed back in the corresponding `results` item.

## Request body

The list of addresses to validate

| Field | Type | Description |
|-------|------|-------------|
| `requests` | array of objects [1..200 items] | The list of address validation requests to make. |
| `requests[].check_id` | string | The unique identifier for this request. This can be used to match the request in the results. Example: `check_123` |
| `requests[].street_address` | string [4..100 characters] or null | First line of the street or postal address. Requires at least one of suburb or postcode to be provided. Example: `Unit 12B, 123-125 Smith St` |
| `requests[].suburb` | string [2..60 characters] or null | Suburb name. Requires street_address to be provided. Example: `Smithtown` |
| `requests[].state` | string or null | State. Requires street_address to be provided. Enum: `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA` Example: `ACT` |
| `requests[].postcode` | string [3..4 characters] or null | Postcode. Requires street_address to be provided. Example: `2000` |
| `requests[].suburb_state_postcode` | string [4..100 characters] or null | Combined suburb, state and postcode. Requires street_address to be provided. Supports various address formats: - Smithtown, ACT 2000 - Smithtown 2000 ACT Example: `Smithtown ACT 2000` |
| `requests[].full_address` | string [4..255 characters] or null | Full address. Supports various address formats: - 123 Smith St, Smithtown, ACT 2000 - Unit 12, 123 Smith Street, Smithtown 2000 ACT - 1/12-34 Smith St, Upper Smithtown, 2000 Example: `Unit 12B, 123-125 Smith St, Smithtown, ACT 2000` |

**Sample request**

```json
{
    "requests": [
        {
            "check_id": "check_123",
            "street_address": "Unit 12B, 123-125 Smith St",
            "suburb": "Smithtown",
            "state": "ACT",
            "postcode": "2000",
            "suburb_state_postcode": "Smithtown ACT 2000",
            "full_address": "Unit 12B, 123-125 Smith St, Smithtown, ACT 2000"
        }
    ]
}
```

## 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` |
| `function` | string | The function that was called. Example: `address_validate_bulk` |
| `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[].check_id` | string or null | The unique identifier for this request. This can be used to match the request in the results. Example: `check_123` |
| `results[].valid` | boolean or null | Indicates if the address is valid. Example: `true` |
| `results[].score` | integer or null | A score from 0 to 10 indicating the quality of the match with 0 being the worst match and 10 being the best match, or null if the address is not valid. Example: `10` |
| `results[].matched_address` | object | The matched address or an empty object if the address is not valid. |
| `results[].address_changes` | array of objects | Array of changes made to the provided address in order to match with the GNAF address. |
| `results[].address_changes[].field` | string | Example: `street_type` |
| `results[].address_changes[].change` | string | Example: `Changed 'St' to 'Rd'` |
| `results[].error` | string | Present if an internal error occurred processing this item. Example: `Internal error` |

**Sample response**

```json
{
    "message": "Ok",
    "function": "address_validate_bulk",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "results": [
        {
            "check_id": "check_123",
            "valid": true,
            "score": 10,
            "matched_address": {
                "address_id": "GAACT714845933",
                "full_address": "Unit 12B, 123-125 Smith St, Smithtown, ACT 2000"
            },
            "address_changes": [
                {
                    "field": "street_type",
                    "change": "Changed 'St' to 'Rd'"
                }
            ],
            "error": "Internal error"
        }
    ]
}
```

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