> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working With Addresses

## Key Requirements

<CardGroup cols={2}>
  <Card title="Address ID Required" icon="id-card">
    Always include the `addressId` when updating addresses. You can retrieve it
    using the `GET /entity` endpoint.
  </Card>

  <Card title="Country Code Required" icon="globe">
    The country field is mandatory and must use ISO-3166-alpha-3 codes (e.g.,
    USA, AUS, GBR).
  </Card>
</CardGroup>

## Available Address Types

We support several address types to help with processing and validation:

<CodeGroup>
  ```typescript title="Address Types"  theme={null}
  type AddressType = | "RESIDENTIAL1" //
  Primary current address | "RESIDENTIAL2" // Previous address | "POSTAL" //
  Mailing address 
  ```
</CodeGroup>

<Callout icon="bell" color="#FFCA16" iconType="regular">
  The legacy `RESIDENTIAL` type will be removed in the next major API version.
  Use `RESIDENTIAL1` instead.
</Callout>

## Address Structure Options

### Option 1: Structured Address (Recommended)

<Callout icon="star" color="#3DD892" iconType="regular">
  Using structured addresses provides better matching results and improved data
  quality.
</Callout>

<AccordionGroup>
  <Accordion title="Address Field Reference">
    | Field          | Type   | Description                                        |
    | -------------- | ------ | -------------------------------------------------- |
    | `unitNumber`   | string | Unit/apartment/suite number                        |
    | `streetNumber` | string | Street number (can be alphanumeric, e.g., "3A")    |
    | `streetName`   | string | Name of the street                                 |
    | `streetType`   | string | Street type (e.g., Road, St, Ave)                  |
    | `town`         | string | Town/city name                                     |
    | `suburb`       | string | Suburb (optional, use only if different from town) |
    | `state`        | string | State abbreviation (e.g., VIC, TX)                 |
    | `region`       | string | County/province (optional)                         |
    | `postalCode`   | string | Postal/ZIP code                                    |
    | `country`      | string | ISO-3166-alpha-3 country code                      |
  </Accordion>

  <Accordion title="Structured Address Example">
    ```json theme={null}
    {
      "addresses": [{
        "addressType": "RESIDENTIAL1",
        "country": "AUS",
        "postalCode": "2000",
        "state": "NSW",
        "streetName": "Main",
        "streetNumber": "42",
        "streetType": "Street",
        "town": "Sydney",
        "unitNumber": "1"
      }]
    }
    ```
  </Accordion>
</AccordionGroup>

### Option 2: Long-Form Address

<Info>Use this format when structured address data isn't available.</Info>

```json theme={null}
{
  "addresses": [
    {
      "addressType": "RESIDENTIAL1",
      "country": "AUS",
      "longForm": "LEVEL 8, 417 ST KILDA ROAD, MELBOURNE, VIC, 3004"
    }
  ]
}
```

## Street Address Flexibility

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  While the `streetName` field is flexible and can contain combined address elements, we recommend separating address components when possible:

  * ✅ Preferred: Separate `streetNumber`, `streetName`, and `streetType`
  * ⚠️ Acceptable: Combined in `streetName`
</Callout>

## Additional Resources

<Card title="ISO Country Codes Reference" icon="globe" href="https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes">
  View the complete list of ISO 3166-1 alpha-3 country codes <Icon icon="arrow-up-right-from-square" size={12} />
</Card>