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

# Addresses

> Manage client addresses

Addresses store physical location information for clients.

## Address Types

| Type       | Description              |
| ---------- | ------------------------ |
| `Home`     | Residential address      |
| `Business` | Business address         |
| `Mailing`  | Mailing address          |
| `Legal`    | Legal registered address |
| `Other`    | Other address type       |

## Creating Addresses

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    import { AddressType } from "@artu-ai/compliance-sdk";

    const address = await sdk.addresses.create({
      clientId: "client_abc123",
      type: AddressType.Home,
      street: "Paseo de la Reforma 222",
      city: "Ciudad de México",
      state: "CDMX",
      postalCode: "06600",
      country: "MX",
      isPrimary: true,
    });
    ```
  </Tab>

  <Tab title="Mexico">
    With a Mexico-scoped SDK, fields are flattened to the root level:

    ```typescript theme={null}
    import { AddressType } from "@artu-ai/compliance-sdk";

    const address = await sdk.addresses.create({
      clientId: "client_abc123",
      type: AddressType.Home,
      street: "Paseo de la Reforma",
      exteriorNumber: "222",        // MX field at root
      interiorNumber: "Piso 5",     // MX field at root
      neighborhood: "Juárez",       // MX field at root
      city: "Ciudad de México",
      state: "CDMX",
      postalCode: "06600",
      country: "MX",
      isPrimary: true,
    });
    ```
  </Tab>
</Tabs>

## Retrieving Addresses

```typescript theme={null}
const address = await sdk.addresses.retrieve("addr_xyz789");

console.log(address.street);
console.log(address.city);
console.log(address.isPrimary);
```

Need to look up by your own IDs or metadata? Use `retrieveByExternalId` or `retrieveByMetadata` (see [SDK reference](/sdk/resources)).

### Accessing Mexico Properties

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    const address = await sdk.addresses.retrieve("addr_xyz789");

    console.log(address.street);
    console.log(address.city);
    console.log(address.formatted);
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    // Returns MexAddress with typed accessors
    const address = await sdk.addresses.retrieve("addr_xyz789");

    console.log(address.exteriorNumber); // "222"
    console.log(address.interiorNumber); // "Piso 5"
    console.log(address.neighborhood);   // "Juárez"
    console.log(address.municipality);   // "Cuauhtémoc"

    // Formatted output
    console.log(address.streetLine);        // "Paseo de la Reforma 222 Int. Piso 5"
    console.log(address.formattedMexican);  // "Paseo de la Reforma 222, Col. Juárez, 06600 Ciudad de México, CDMX"
    ```
  </Tab>
</Tabs>

## Updating Addresses

<Tabs>
  <Tab title="Base">
    ```typescript theme={null}
    const updated = await sdk.addresses.update("addr_xyz789", {
      street: "Paseo de la Reforma 225",
      postalCode: "06601",
    });
    ```
  </Tab>

  <Tab title="Mexico">
    ```typescript theme={null}
    const updated = await sdk.addresses.update("addr_xyz789", {
      interiorNumber: "Piso 6",
      neighborhood: "Roma Norte",
    });
    ```
  </Tab>
</Tabs>

## Listing Addresses

### By Client

```typescript theme={null}
const { data } = await sdk.addresses.listByClient("client_abc123");

for (const address of data) {
  console.log(address.formatted);
}
```

### With Filtering

```typescript theme={null}
import { AddressType } from "@artu-ai/compliance-sdk";

const { data } = await sdk.addresses.list({
  filter: {
    clientId: "client_abc123",
    type: AddressType.Legal,
  },
});
```

### Get Primary Address

```typescript theme={null}
const primary = await sdk.addresses.getPrimary("client_abc123");

if (primary) {
  console.log(`Primary address: ${primary.formatted}`);
}

// Filter by type
const primaryLegal = await sdk.addresses.getPrimary(
  "client_abc123",
  AddressType.Legal,
);
```

## Deleting Addresses

```typescript theme={null}
await sdk.addresses.delete("addr_xyz789");
```

## Address Model Properties

<Tabs>
  <Tab title="Base">
    | Property             | Type          | Description              |
    | -------------------- | ------------- | ------------------------ |
    | `id`                 | `string`      | Unique identifier        |
    | `clientId`           | `string`      | Parent client ID         |
    | `type`               | `AddressType` | Address type             |
    | `isPrimary`          | `boolean`     | Whether primary address  |
    | `street`             | `string`      | Street name              |
    | `city`               | `string`      | City name                |
    | `state`              | `string`      | State/province           |
    | `postalCode`         | `string`      | Postal/ZIP code          |
    | `country`            | `CountryIso2` | Country code             |
    | `isHome`             | `boolean`     | True if home address     |
    | `isBusiness`         | `boolean`     | True if business address |
    | `isMailing`          | `boolean`     | True if mailing address  |
    | `isLegal`            | `boolean`     | True if legal address    |
    | `formatted`          | `string`      | Single-line formatted    |
    | `formattedMultiLine` | `string`      | Multi-line formatted     |
    | `createdAt`          | `Date`        | Creation timestamp       |
    | `updatedAt`          | `Date`        | Last update timestamp    |
  </Tab>

  <Tab title="Mexico">
    Includes all base properties plus:

    | Property                    | Type     | Description                |
    | --------------------------- | -------- | -------------------------- |
    | `exteriorNumber`            | `string` | Número exterior            |
    | `interiorNumber`            | `string` | Número interior            |
    | `neighborhood`              | `string` | Colonia                    |
    | `municipality`              | `string` | Municipio/Alcaldía         |
    | `betweenStreets`            | `string` | Entre calles               |
    | `reference`                 | `string` | Referencia                 |
    | `streetLine`                | `string` | Street with numbers        |
    | `formattedMexican`          | `string` | Mexican format single-line |
    | `formattedMexicanMultiLine` | `string` | Mexican format multi-line  |
  </Tab>
</Tabs>

## Batch Operations

```typescript theme={null}
// Create multiple addresses
const result = await sdk.addresses.createMany([
  {
    clientId: "client_abc123",
    type: AddressType.Home,
    street: "Calle Principal",
    ...
  },
  {
    clientId: "client_abc123",
    type: AddressType.Business,
    street: "Av. Empresarial",
    ...
  },
]);
```

<Info>See [Batch Operations](/guides/batch-operations) for more details.</Info>