API referenceAddress Book

Update an address book entry

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.

PATCH/address-book/{addressId}

https://sandbox.api.mothership.com/beta

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
  }
}'

Reads your token from $MOTHERSHIP_API_TOKEN

Response

{

: {

: "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",

: "string",

: "Chemtrec",

: {

: "2800 E Observatory Rd",

: "string",

: "Los Angeles",

: "CA",

: "90027"

: "string",

: "0900",

: "1700",

: {

: "string",

: "+15555555555",

: "string",

: "logistics@example.com",

: "Dock door 3",

: [

"string"

]

: {

: "string",

: "+15555555555",

: "string",

: "logistics@example.com",

: "Dock door 3",

: [

"string"

]

: "2026-03-19T17:00:00.000Z",

: "2026-03-19T17:00:00.000Z"

}

Hover a key to see what it means. Click it to jump to the field.

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, unless the stop already has it saved. Without the feature, adding it returns 400 INVALID_REQUEST.

Authorization

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Path parameters

addressIdstring<uuid>Required
ID of the address book entry

Request body

application/json · required

nicknamestring
Your own name for this location
On update, leave it out to keep the saved value or send null to clear it.
min length 1max length 100nullable
companyNamestring
Business or company name at this location
On update, leave it out to keep the saved value or send null to clear it.
min length 1max length 100nullable
openTimestring
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.
4 characterspattern ^([01]\d|2[0-3])[0-5]\d$nullable
closeTimestring
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.
4 characterspattern ^([01]\d|2[0-3])[0-5]\d$nullable
pickupobject
Contact, services and driver notes used when this location is a pickup
deliveryobject
Contact, services and driver notes used when this location is a delivery
addressobject
Address of this location. Replaces the whole saved address, so a subStreet left out is cleared.

Responses

- dataobjectRequired
  idstring<uuid>Required
  ID of the address book entry
  nicknamestringRequired
  Your own name for this location
  nullable
  companyNamestringRequired
  Business or company name at this location
  nullable
  addressobjectRequired
  formattedAddressstringRequired
  The full address on one line
  openTimestringRequired
  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
  4 characterspattern ^[0-9]{4}$nullable
  closeTimestringRequired
  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
  4 characterspattern ^[0-9]{4}$nullable
  pickupobjectRequired
  deliveryobjectRequired
  createdAtstring<date-time>Required
  ISO string of when the entry was created
  updatedAtstring<date-time>Required
  ISO string of when the entry was last changed