# List address book entries

`GET https://api.mothership.com/beta/address-book`

Sandbox: `https://sandbox.api.mothership.com/beta/address-book`

This endpoint lists the locations saved in your organization's address book, most recently changed first.

## Authorization

Send your API token as a Bearer token: `Authorization: Bearer <token>`.

## Query parameters

- `perPage` (integer, optional, default 25, min 1, max 100): Maximum number of entries returned for each page - if not provided, this will default to 25.
- `page` (integer, optional, default 1, min 1): Page to return, starting at 1. Defaults to 1.

## Responses

### 200

A page of address book entries, wrapped inside an object named "data"

- `data` (object, required)
  - `results` (array of objects, required): Entries on this page, most recently changed first.
    - `id` (string<uuid>, required): ID of the address book entry.
    - `nickname` (string, required, nullable): Your own name for this location.
    - `companyName` (string, required, nullable): Business or company name at this location.
    - `address` (object, required)
      - `street` (string, required): Street address.
      - `subStreet` (string, required, nullable): Substreet of the address, such as suite number or letter.
      - `city` (string, required): City.
      - `state` (string, required): 2-letter uppercase state abbreviation of the address.
      - `zip` (string, required): ZIP code.
    - `formattedAddress` (string, required): The full address on one line.
    - `openTime` (string, required, 4 characters, pattern ^[0-9]{4}$, nullable): Open time of this location, in 4-digit 24-hour time format (HHmm) of this location's timezone. For example: 0900 to represent 9:00am in local time.
    - `closeTime` (string, required, 4 characters, pattern ^[0-9]{4}$, nullable): Close time of this location, in 4-digit 24-hour time format (HHmm) of this location's timezone. Must be later than openTime. For example: 1700 to represent 5:00pm in local time.
    - `pickup` (object, required)
      - `contactName` (string, required, nullable): Full name of the contact at this location.
      - `phoneNumber` (string, required, nullable): Contact's US phone number in E.164 format For example: +17148130000.
      - `phoneExtension` (string, required, nullable): Contact's phone extension, up to 10 digits.
      - `email` (string, required, nullable): Contact's email.
      - `notes` (string, required, nullable): Instructions for the driver at this location.
      - `accessorials` (array of strings, required): Accessorials required at this location. notifyBeforeArrival is delivery only, and only for users it is enabled for, as on quotes. A service saved on the dashboard that this API has no name for comes back as stored, such as white-glove-delivery. On update, the list replaces the saved one but keeps those services, so leave them out of the list you send.
    - `delivery` (object, required)
      - `contactName` (string, required, nullable): Full name of the contact at this location.
      - `phoneNumber` (string, required, nullable): Contact's US phone number in E.164 format For example: +17148130000.
      - `phoneExtension` (string, required, nullable): Contact's phone extension, up to 10 digits.
      - `email` (string, required, nullable): Contact's email.
      - `notes` (string, required, nullable): Instructions for the driver at this location.
      - `accessorials` (array of strings, required): Accessorials required at this location. notifyBeforeArrival is delivery only, and only for users it is enabled for, as on quotes. A service saved on the dashboard that this API has no name for comes back as stored, such as white-glove-delivery. On update, the list replaces the saved one but keeps those services, so leave them out of the list you send.
    - `createdAt` (string<date-time>, required): ISO string of when the entry was created.
    - `updatedAt` (string<date-time>, required): ISO string of when the entry was last changed.
  - `page` (integer, required, min 1): Current page of entries.
  - `perPage` (integer, required, min 1): Maximum number of entries returned for each page.
  - `total` (integer, required, min 0): Number of entries in the address book.
  - `hasMore` (boolean, required): True if more entries can be fetched from a subsequent page.

## Example request

```bash
curl --request GET \
  --url 'https://sandbox.api.mothership.com/beta/address-book' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json'
```

## Example response (200)

```json
{
  "data": {
    "results": [
      {
        "id": "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
        "nickname": "string",
        "companyName": "Chemtrec",
        "address": {
          "street": "2800 E Observatory Rd",
          "subStreet": "string",
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90027"
        },
        "formattedAddress": "string",
        "openTime": "0900",
        "closeTime": "1700",
        "pickup": {
          "contactName": "string",
          "phoneNumber": "+15555555555",
          "phoneExtension": "string",
          "email": "logistics@example.com",
          "notes": "Dock door 3",
          "accessorials": [
            "string"
          ]
        },
        "delivery": {
          "contactName": "string",
          "phoneNumber": "+15555555555",
          "phoneExtension": "string",
          "email": "logistics@example.com",
          "notes": "Dock door 3",
          "accessorials": [
            "string"
          ]
        },
        "createdAt": "2026-03-19T17:00:00.000Z",
        "updatedAt": "2026-03-19T17:00:00.000Z"
      }
    ],
    "page": 1,
    "perPage": 25,
    "total": 1,
    "hasMore": true
  }
}
```