# Create an address book entry

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

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

This endpoint saves a location to your organization's address book. Mothership looks the address up to fill in its coordinates and timezone. If that fails, the entry is still saved and the response carries a warning.

Only `address` is required. Mothership looks the address up to fill in its coordinates and timezone. If the lookup fails, the entry is still saved and the response has a `warnings` array.

An organization can save an address once. Saving one that is already in the address book returns `409` with the `INVALID_REQUEST` type; change the saved entry with [Update an address book entry](https://docs.mothership.com/reference/updateaddressbookentry) instead.

`openTime`, `closeTime` and `phoneNumber` take the same formats as a location on [Create a quote](https://docs.mothership.com/reference/createquote), so a saved entry can fill a quote's pickup or delivery. `accessorials` use the quote's names but take only the services the address book saves at each stop: `hazmat` isn't one, and delivery also takes `fbaAppointment`, which Create a quote doesn't.

## Authorization

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

## Request body

- `address` (object, required): Address of this location.
  - `street` (string, required, min length 1, max length 200): Street address.
  - `city` (string, required, min length 1, max length 100): City.
  - `state` (string, required, pattern ^[A-Z]{2}$): 2-letter uppercase state abbreviation of the address.
  - `zip` (string, required, min length 1, max length 20): ZIP code.
  - `subStreet` (string, optional, min length 1, max length 100, nullable): Substreet of the address, such as suite number or letter.
- `nickname` (string, optional, min length 1, max length 100, nullable): Your own name for this location On update, leave it out to keep the saved value or send null to clear it.
- `companyName` (string, optional, min length 1, max length 100, nullable): Business or company name at this location On update, leave it out to keep the saved value or send null to clear it.
- `openTime` (string, optional, 4 characters, pattern ^([01]\d|2[0-3])[0-5]\d$, 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 On update, leave it out to keep the saved value or send null to clear it.
- `closeTime` (string, optional, 4 characters, pattern ^([01]\d|2[0-3])[0-5]\d$, 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 On update, leave it out to keep the saved value or send null to clear it.
- `pickup` (object, optional): Contact, services and driver notes used when this location is a pickup.
  - `contactName` (string, optional, min length 1, max length 200, nullable): Full name of the contact at this location On update, leave it out to keep the saved value or send null to clear it.
  - `phoneNumber` (string, optional, pattern ^\+1\d{10}$, nullable): Contact's US phone number in E.164 format For example: +17148130000 On update, leave it out to keep the saved value or send null to clear it.
  - `phoneExtension` (string, optional, pattern ^\d{1,10}$, nullable): Contact's phone extension, up to 10 digits On update, leave it out to keep the saved value or send null to clear it.
  - `email` (string<email>, optional, min length 1, max length 254, nullable): Contact's email On update, leave it out to keep the saved value or send null to clear it.
  - `notes` (string, optional, min length 1, max length 500, nullable): Instructions for the driver at this location On update, leave it out to keep the saved value or send null to clear it.
  - `accessorials` (array of strings, optional, unique items): 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. One of: `liftgate`, `inside`, `residential`, `appointment`, `tradeshow`, `twicRequired`, `crossDock`, `cfs`, `limitedAccess`.
- `delivery` (object, optional): Contact, services and driver notes used when this location is a delivery.
  - `contactName` (string, optional, min length 1, max length 200, nullable): Full name of the contact at this location On update, leave it out to keep the saved value or send null to clear it.
  - `phoneNumber` (string, optional, pattern ^\+1\d{10}$, nullable): Contact's US phone number in E.164 format For example: +17148130000 On update, leave it out to keep the saved value or send null to clear it.
  - `phoneExtension` (string, optional, pattern ^\d{1,10}$, nullable): Contact's phone extension, up to 10 digits On update, leave it out to keep the saved value or send null to clear it.
  - `email` (string<email>, optional, min length 1, max length 254, nullable): Contact's email On update, leave it out to keep the saved value or send null to clear it.
  - `notes` (string, optional, min length 1, max length 500, nullable): Instructions for the driver at this location On update, leave it out to keep the saved value or send null to clear it.
  - `accessorials` (array of strings, optional, unique items): 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. One of: `liftgate`, `inside`, `residential`, `appointment`, `tradeshow`, `twicRequired`, `notifyBeforeArrival`, `cfs`, `homeDelivery`, `limitedAccess`, `fbaAppointment`.

## Responses

### 201

The created entry, wrapped inside an object named "data"

- `data` (object, required)
  - `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.
- `warnings` (array of objects, optional)
  - `type` (string, required): What the warning is about. ADDRESS_NOT_VERIFIED: the entry was saved, but Mothership could not look the address up, so its coordinates, timezone or residential status are missing. One of: `ADDRESS_NOT_VERIFIED`.
  - `message` (string, required): What happened, in words you can show a user.

### 409

Another address book entry already has this address

- `code` (number, required) One of: `100`, `101`, `200`, `201`, `202`, `203`, `204`, `205`, `206`, `300`, `301`, `302`, `303`, `304`, `305`, `307`, `400`, `401`, `402`, `403`, `404`, `405`, `406`, `407`, `408`, `409`, `410`, `411`, `412`, `413`, `414`, `415`, `416`, `417`, `422`, `429`, `500`, `501`, `502`, `503`, `504`, `505`.
- `type` (string, required) One of: `UNKNOWN`, `NOT_FOUND`, `SERVER_ERROR`, `UNAUTHENTICATED`, `MISSING_PERMISSION`, `INVALID_REQUEST`, `RATE_LIMIT_EXCEEDED`, `CARGO_TOO_LARGE`, `NO_RATES_FOUND`, `QUOTE_NOT_PURCHASABLE`, `PAYMENT_REQUIRED`, `PAYMENT_FAILED`.
- `message` (string, required)
- `metadata` (object, optional)

## Example request

```bash
curl --request POST \
  --url 'https://sandbox.api.mothership.com/beta/address-book' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "nickname": "Main warehouse",
  "companyName": "Acme Supply",
  "address": {
    "street": "1200 E 5th St",
    "subStreet": "Dock 4",
    "city": "Austin",
    "state": "TX",
    "zip": "78702"
  },
  "openTime": "0800",
  "closeTime": "1700",
  "pickup": {
    "contactName": "Jane Doe",
    "phoneNumber": "+15125550100",
    "email": "shipping@acmesupply.com",
    "notes": "Check in at the guard shack.",
    "accessorials": [
      "liftgate"
    ]
  },
  "delivery": {
    "contactName": "Sam Lee",
    "phoneNumber": "+15125550101",
    "phoneExtension": "12",
    "accessorials": [
      "appointment"
    ]
  }
}'
```

## Example response (201)

```json
{
  "data": {
    "id": "6f1c2b0e-8a4d-4e21-9b7f-2d3c4a5b6e7f",
    "nickname": "Main warehouse",
    "companyName": "Acme Supply",
    "address": {
      "street": "1200 E 5th St",
      "subStreet": "Dock 4",
      "city": "Austin",
      "state": "TX",
      "zip": "78702"
    },
    "formattedAddress": "1200 E 5th St, Dock 4, Austin, TX 78702",
    "openTime": "0800",
    "closeTime": "1700",
    "pickup": {
      "contactName": "Jane Doe",
      "phoneNumber": "+15125550100",
      "phoneExtension": null,
      "email": "shipping@acmesupply.com",
      "notes": "Check in at the guard shack.",
      "accessorials": ["liftgate"]
    },
    "delivery": {
      "contactName": "Sam Lee",
      "phoneNumber": "+15125550101",
      "phoneExtension": "12",
      "email": null,
      "notes": null,
      "accessorials": ["appointment"]
    },
    "createdAt": "2026-10-29T17:04:12.381Z",
    "updatedAt": "2026-10-29T17:04:12.381Z"
  }
}
```