> For the complete documentation index, see [llms.txt](https://developer.flash-payments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.flash-payments.com/compliance/address-cleanser/cleanse-an-address.md).

# Cleanse an address

### Address Cleanser

To cleanse an address, execute the `cleanseAddress` mutation as below. The result is returned synchronously — no polling or webhooks are required.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const bodyJSON = {
  variables: {
    input: {
      street: "33 effingham st, sth launceston 7249",
      country: "AU",
    },
  },
  query: `
fragment AddressParts on Address { building streetNo street suburb state postcode country }

mutation ($input: AddressInput!) {
  cleanseAddress(input: $input) {
    success
    code
    message
    addressRequest {
      id
      originalAddress { ...AddressParts }
      cleansedAddress { ...AddressParts }
      recommendation
      score
    }
  }
}`,
};
```

{% endtab %}

{% tab title="GraphQL Query" %}

```graphql
fragment AddressParts on Address { building streetNo street suburb state postcode country }

mutation($input: AddressInput!) {
  cleanseAddress(input: $input) {
    success
    code
    message
    addressRequest {
      id
      originalAddress { ...AddressParts }
      cleansedAddress { ...AddressParts }
      recommendation
      score
    }
  }
}
```

{% endtab %}

{% tab title="Variables" %}

```json
{
  "input": {
    "street": "33 effingham st, sth launceston 7249",
    "country": "AU"
  }
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "data": {
    "cleanseAddress": {
      "success": true,
      "code": "CLEANSED",
      "message": "Address cleansed",
      "addressRequest": {
        "id": "6820a4f3e1c2b5d8f0123456",
        "originalAddress": {
          "building": null,
          "streetNo": null,
          "street": "33 effingham st, sth launceston 7249",
          "suburb": null,
          "state": null,
          "postcode": null,
          "country": "AU"
        },
        "cleansedAddress": {
          "building": null,
          "streetNo": null,
          "street": "33 Effingham Street",
          "suburb": "South Launceston",
          "state": "TAS",
          "postcode": "7249",
          "country": "AU"
        },
        "recommendation": "accept",
        "score": 97.1
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`originalAddress` and `cleansedAddress` are both of type `Address`, so the examples above declare a reusable [GraphQL fragment](https://graphql.org/learn/queries/#fragments) — `fragment AddressParts on Address { ... }` — and spread it into both with `...AddressParts` instead of repeating the field list.
{% endhint %}

**Address — `input`**

The standard `AddressInput` type is used:

| Field      | Description                                                               |
| ---------- | ------------------------------------------------------------------------- |
| `street`   | Street string, e.g. `Apt 256 123 John Ave`. **Required**                  |
| `country`  | Two-letter ISO 3166-1 alpha-2 country code, e.g. `AU`, `US`. **Required** |
| `building` | Building part of the address, where applicable (e.g. HK, SG). *Optional*  |
| `streetNo` | Street number, e.g. `33`. *Optional*                                      |
| `suburb`   | Suburb, city or other locality, e.g. `Paddington`. *Optional*             |
| `state`    | State of the country, e.g. `NSW`. *Optional*                              |
| `postcode` | Post code (aka zip code), e.g. `2000`. *Optional*                         |

Addresses from most countries worldwide are supported.

**Optional fields**

Only `street` and `country` are required. The other components — `building`, `streetNo`, `suburb`, `state`, `postcode` — are optional: you can either supply them separately, or fold them into `street` as a single free-form string (e.g. `"Unit 5, 33 Effingham St, South Launceston TAS 7249"`).

Either way, `originalAddress` keeps your input exactly as you sent it.

**Result — `recommendation` and `score`**

The result is an estimate, not a definitive check. Inspect `recommendation` (`accept`, `review`, `flag`) and `score` (0 to 100, higher is a closer match) on the returned `addressRequest` to decide how to treat the cleansed address. See the overview for details.

**Response codes**

| Code                            | Meaning                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `CLEANSED`                      | The address was cleansed and the result is in `addressRequest`                 |
| `ALREADY_CLEANSED`              | The same address was already cleansed today — the existing request is returned |
| `VALIDATION_ERROR`              | The input failed validation — e.g. `street` is missing                         |
| `CLEANSING_FAILED`              | The address could not be processed — the request is not billable               |
| `LIMIT_EXCEEDED`                | The free monthly request limit was reached                                     |
| `ADDRESS_CLEANSER_API_DISABLED` | The API is not enabled for your account — contact support                      |

**Deduplication**

If you submit the same address more than once within the same calendar day, the existing request is returned rather than creating a new one, with `code: ALREADY_CLEANSED`. You are billed at most once per day for the same address.

**Monthly request limit**

1,000 requests per month are included free of charge. Once reached, `success: false` is returned with `code: LIMIT_EXCEEDED`. Contact support to upgrade your account.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.flash-payments.com/compliance/address-cleanser/cleanse-an-address.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.