> ## 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 for Updates" icon="id-card">
    When updating an existing address, always include the `addressId`. You can
    retrieve it from the `addresses` array in the entity response.
  </Card>

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

## V2 Address Model: What's Changed

The v2 address schema introduces two key structural changes from v1:

**1. `type` + `status` replaces `addressType`**

In v1, address purpose and history were encoded in a single `addressType` field
(e.g., `RESIDENTIAL1`, `RESIDENTIAL2`). In v2, these are separated:

* `type` — what kind of address it is (e.g., `RESIDENTIAL`, `POSTAL`)
* `status` — the temporal state of that address (`CURRENT`, `PREVIOUS`, `FUTURE`)

**2. Field names align to global address standards**

| v1 Field      | v2 Field       | Notes                                                |
| ------------- | -------------- | ---------------------------------------------------- |
| `addressType` | `type`         | See `Address-TypeEnum` below                         |
| `town`        | `locality`     | Town, suburb, village, or city                       |
| `suburb`      | `neighborhood` | Only needed when suburb differs from locality        |
| `state`       | `subdivision`  | Use ISO 3166-2 sub-division code (e.g., `VIC`, `TX`) |
| `region`      | `district`     | District, county, province, or cantonment            |

***

## Address Types

The `type` field accepts the following values:

| Value                       | Description                                                 |
| --------------------------- | ----------------------------------------------------------- |
| `RESIDENTIAL`               | Personal residential address                                |
| `POSTAL`                    | Individual mailing address                                  |
| `BUSINESS`                  | Business address                                            |
| `REGISTERED_OFFICE`         | Registered office address                                   |
| `PLACE_OF_BUSINESS`         | Principal place of business                                 |
| `OFFICIAL_CORRESPONDANCE`   | Business postal/mailing address                             |
| `PLACE_OF_BIRTH`            | Place of birth                                              |
| `OFFICE_LOCALITY`           | Office locality                                             |
| `AUTHORITATIVE_RESIDENTIAL` | Authoritative residential address returned by a data source |
| `OTHER`                     | Any other address type                                      |

Use `type` in conjunction with `status` to express address history. For example,
a current home address is `type: RESIDENTIAL, status: CURRENT`. A previous home
address is `type: RESIDENTIAL, status: PREVIOUS`.

<Callout icon="bell" color="#FFCA16" iconType="regular">
  The v1 `RESIDENTIAL1` / `RESIDENTIAL2` pattern is not used in v2. Use
  `RESIDENTIAL` with `status: CURRENT` or `PREVIOUS` instead.
</Callout>

***

## Address Status

The `status` field must be used alongside `type` to indicate the temporal state
of the address.

| Value      | Description                           |
| ---------- | ------------------------------------- |
| `CURRENT`  | The address is currently in use       |
| `PREVIOUS` | The address was used in the past      |
| `FUTURE`   | The address is planned for future use |

***

## Address Structure Options

### Option 1: Structured Address (Recommended)

<Callout icon="star" color="#3DD892" iconType="regular">
  Providing structured address components produces better matching results and
  improved data quality than long-form input.
</Callout>

<AccordionGroup>
  <Accordion title="Address Field Reference">
    | Field          | Type   | Required     | Description                                                                             |
    | -------------- | ------ | ------------ | --------------------------------------------------------------------------------------- |
    | `addressId`    | string | For updates  | Assigned when an address is added. Must be included when modifying an existing address. |
    | `type`         | string |              | Address type. See `Address-TypeEnum`.                                                   |
    | `status`       | string |              | Address status: `CURRENT`, `PREVIOUS`, or `FUTURE`. Use with `type`.                    |
    | `unitNumber`   | string |              | Unit, apartment, flat, or suite number                                                  |
    | `buildingName` | string |              | Name of the building, apartment block, or condominium                                   |
    | `streetNumber` | string |              | Property number on the street. Can be alphanumeric (e.g., `3A`)                         |
    | `streetName`   | string |              | Name of the street. See note below on `addressLine1` input.                             |
    | `streetType`   | string |              | Street type (e.g., `Road`, `Street`, `Ave`, `Circuit`)                                  |
    | `locality`     | string |              | Town, village, suburb, or city                                                          |
    | `neighborhood` | string |              | Suburb or neighborhood — only supply if you also need a separate `locality` value       |
    | `subdivision`  | string |              | State or administrative sub-division. Use ISO 3166-2 code (e.g., `VIC`, `TX`)           |
    | `district`     | string |              | District, county, province, or cantonment                                               |
    | `postalCode`   | string |              | Postal or ZIP code                                                                      |
    | `country`      | string | **Required** | ISO 3166-1 alpha-3 country code (e.g., `AUS`, `USA`, `GBR`)                             |
    | `careOf`       | string |              | Individual or business at this address, if different from the entity name               |
    | `validFrom`    | Date   |              | Date this address first became active. Used primarily with business addresses.          |
    | `validTo`      | Date   |              | Date this address was no longer in use. Used primarily with business addresses.         |
  </Accordion>

  <Accordion title="Structured Address Example (AUS)">
    ```json theme={null}
        {
          "addresses": [
            {
              "type": "RESIDENTIAL",
              "status": "CURRENT",
              "unitNumber": "1",
              "streetNumber": "100",
              "streetName": "South",
              "streetType": "ST",
              "locality": "Sydney",
              "subdivision": "NSW",
              "postalCode": "2000",
              "country": "AUS"
            }
          ]
        }
    ```
  </Accordion>

  <Accordion title="Update Address Example (AUS)">
    When updating an existing address, include `addressId` to target the correct record.

    ```json theme={null}
        {
          "addresses": [
            {
              "addressId": "<existing-address-id>",
              "type": "RESIDENTIAL",
              "status": "CURRENT",
              "streetNumber": "123",
              "streetName": "King",
              "streetType": "Street",
              "locality": "Melbourne",
              "subdivision": "VIC",
              "postalCode": "3000",
              "country": "AUS"
            }
          ]
        }
    ```
  </Accordion>
</AccordionGroup>

***

### Option 2: Long-Form Address

<Info>
  Use this format only when structured address components are not available.
  The API will attempt to parse `longForm` into its constituent fields.
  Results are not guaranteed — ambiguous or unparsable addresses will return
  an error.
</Info>

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

***

## Using `streetName` for Combined Address Input

If your system stores street details in a single field (commonly called
`addressLine1`, e.g., `"42 Main Street"`), place the full value in `streetName`.
The `streetName` field can accommodate combined address elements when discrete
fields are unavailable.

<Callout icon="thumbtack" color="#1A6CFF" iconType="regular">
  For best matching results, provide `streetNumber`, `streetName`, and
  `streetType` as separate fields wherever possible.

  * ✅ **Preferred:** `streetNumber: "42"`, `streetName: "Main"`, `streetType: "Street"`
  * ⚠️ **Acceptable fallback:** `streetName: "42 Main Street"` (combined `addressLine1` value)
</Callout>

***

## Read-Only Response Fields

The following address fields are returned in API responses but cannot be set
in request payloads:

| Field                  | Description                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `addressId`            | Assigned by FrankieOne when an address is first created                                    |
| `sourceId`             | Links to the `informationSources` map — indicates which data source populated this address |
| `unstructuredLongForm` | Raw, unformatted address as received from the source. Not normalised or standardised.      |

***

## 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>