# List a customer's addresses

URL: https://docs.sparklayer.io/developers/api/customers/list-a-customers-addresses
Operation: `GET /api/v2/customers/{lookupBy}/{identifier}/addresses` (operationId `listCustomerAddresses`)
OpenAPI spec: https://docs.sparklayer.io/openapi/customers.yaml

Returns all the customer's addresses, as a single array.

`GET /api/v2/customers/{lookupBy}/{identifier}/addresses`

**Base URLs:** `https://app.sparklayer.io` (Live), `https://test.app.sparklayer.io` (Test)

**Authentication:** send `Authorization: Bearer <access_token>` and `Site-Id: <site id>` with every request. Get the token from [Get an access token](https://docs.sparklayer.io/developers/api/core/get-an-access-token.md); see [Authentication](https://docs.sparklayer.io/developers/authentication.md).

### Example request

```bash
curl "https://app.sparklayer.io/api/v2/customers/platform/7843024560291/addresses" \
  -H "Authorization: Bearer $SPARKLAYER_TOKEN" \
  -H "Site-Id: $SPARKLAYER_SITE_ID"
```

Set `SPARKLAYER_TOKEN` to an access token and `SPARKLAYER_SITE_ID` to your Site ID. For the test environment, use `https://test.app.sparklayer.io`.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lookupBy` | "sparklayer" \| "platform" \| "email" | Yes | What `identifier` is: `sparklayer` (the customer's SparkLayer ID), `platform` (their ID on your eCommerce platform) or `email` (their email address). Example: `platform` |
| `identifier` | string | Yes | The customer's ID or email address, of the kind set by `lookupBy`. SparkLayer IDs are UUIDs; legacy `cu_` IDs work too, except for shopping lists and favourites. Email lookups are exact and case-sensitive: URL-encode the address, with `+` as `%2B`. Example: `7843024560291` |

### Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Site-Id` | string | Yes | Your SparkLayer Site ID, from Settings > API in the SparkLayer Dashboard. Length: min 1. Example: `jones-climbing` |

### Responses

#### 200: Successful response

An array. Each item:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `[].id` | string (uuid) | | SparkLayer Customer Address ID |
| `[].legacy_id` | string \| null | | Legacy SparkLayer Customer Address ID |
| `[].created_at` | string (date-time) | | Created At |
| `[].updated_at` | string (date-time) | | Updated At |
| `[].title` | string \| null | | Title. Length: max 30. |
| `[].first_name` | string | Yes | First Name. Length: max 50. |
| `[].last_name` | string | Yes | Last Name. Length: max 50. |
| `[].company` | string \| null | | Company. Length: max 128. |
| `[].address_line1` | string | Yes | Address Line 1. Length: min 1, max 255. |
| `[].address_line2` | string \| null | | Address Line 2. Length: max 255. |
| `[].city` | string | Yes | City. Length: min 1, max 128. |
| `[].region_name` | string \| null | | Region Name (readonly). Length: max 128. |
| `[].region_code` | string \| null | Yes | The region within the country, such as `CA` for California. Optional, but if you send it, it must be a region of `country_code`. Length: max 10. |
| `[].postal_code` | string | | Postal Code. Length: max 20. |
| `[].country_name` | string | | Country Name (readonly). Length: max 3. |
| `[].country_code` | string | Yes | The 2-letter ISO 3166-1 country code, such as `GB`. Length: max 2. |
| `[].phone` | string \| null | | Phone. Length: max 20. |
| `[].external_id` | string \| null | | The identifier for the address on the e-commerce platform. Length: min 1, max 124. |
| `[].is_default_shipping` | boolean | | |
| `[].is_default_billing` | boolean | | |
| `[].valid_for_purchase_id` | string (uuid) \| null | | A temporary address (typically used for drop shipping) only valid for a purchase ID |

```json
[
  {
    "id": "9151f21f-43ae-43b4-92f3-f4af67cdf544",
    "legacy_id": "ca_47",
    "created_at": "2026-01-31T09:00:00Z",
    "updated_at": "2026-01-31T09:00:00Z",
    "title": "Mr",
    "first_name": "Bob",
    "last_name": "Jones",
    "company": "Tom Jones Climbing Ltd",
    "address_line1": "Example Industrial Estate",
    "address_line2": "North Country",
    "city": "Cityland",
    "region_name": "California",
    "region_code": "CA",
    "postal_code": "12345",
    "country_name": "USA",
    "country_code": "US",
    "phone": "+44 (0) 123456789",
    "external_id": "123456789",
    "is_default_shipping": true,
    "is_default_billing": true,
    "valid_for_purchase_id": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b"
  }
]
```

#### Other statuses: An error. The body describes the problem: see [Errors](https://docs.sparklayer.io/developers/errors.md).

`application/problem+json`: the standard error body (below).

### Error body

Error responses with a body use this RFC 7807 problem details object. See [Errors](https://docs.sparklayer.io/developers/errors.md) for every status code and which errors to retry.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | | Human-readable summary of the error |
| `status` | integer | | HTTP Status code returned from API |
| `title` | string | | Machine-readable error code |
| `type` | string | | |
| `errors` | object[] | | |
| `errors[].code` | string | | A machine-readable error message |
| `errors[].property` | string | | The offending property, with the full path |
| `errors[].field` | string | | The offending property, stripped of the path |
| `errors[].message` | string | | A human-readable summary of the error |

```json
{
  "detail": "Data Validation Failed",
  "status": 400,
  "title": "invalid-api-request-contents",
  "type": "https://hub.sparklayer.io/tech-docs",
  "errors": [
    {
      "code": "unique-constraint-violation",
      "property": "purchase_identifiers.sparklayer",
      "field": "sparklayer",
      "message": "Each stock level must have a unique stock location and sku combination"
    }
  ]
}
```