# Update an address book entry

`PATCH https://api.mothership.com/beta/address-book/{addressId}`

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

This endpoint changes the address book entry represented by addressId. A field left out keeps its saved value and null clears it. A new address replaces the saved one whole. Accessorials replace the stop's saved list, but services saved on the dashboard that this API has no name for are kept.

Send only the fields to change. A field left out keeps its saved value, and `null` clears it. `address` replaces the whole saved address, so a `subStreet` left out of it is cleared. `accessorials` replaces the stop's saved list; send `[]` to clear it. Services saved on the dashboard that this API has no name for stay saved either way.

An entry's accessorials can be sent back as they are, except a service saved on the dashboard that this API has no name for, which comes back as stored, such as `white-glove-delivery`. Leave those out; they stay saved. `notifyBeforeArrival` is delivery only and needs the feature enabled for your user, as on [Create a quote](https://docs.mothership.com/reference/createquote), unless the stop already has it saved. Without the feature, adding it returns `400 INVALID_REQUEST`.

## Authorization

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

## Path parameters

- `addressId` (string<uuid>, required): ID of the address book entry.

## Request body

- `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`.
- `address` (object, optional): Address of this location. Replaces the whole saved address, so a subStreet left out is cleared.
  - `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.

## Responses

### 200

The updated 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.

### 404

No address book entry with the given id exists for the caller organization

- `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)

### 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 PATCH \
  --url 'https://sandbox.api.mothership.com/beta/address-book/addressId' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "closeTime": "1800",
  "delivery": {
    "notes": "Use the north gate.",
    "phoneExtension": null
  }
}'
```

## Example response (200)

```json
{
  "data": {
    "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"
  }
}
```