API referenceAddress Book

Create an address book entry

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.

POST/address-book

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

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

Reads your token from $MOTHERSHIP_API_TOKEN

Response

{

: {

: "6f1c2b0e-8a4d-4e21-9b7f-2d3c4a5b6e7f",

: "Main warehouse",

: "Acme Supply",

: {

: "1200 E 5th St",

: "Dock 4",

: "Austin",

: "TX",

: "78702"

: "1200 E 5th St, Dock 4, Austin, TX 78702",

: "0800",

: "1700",

: {

: "Jane Doe",

: "+15125550100",

: null,

: "shipping@acmesupply.com",

: "Check in at the guard shack.",

: [

"liftgate"

]

: {

: "Sam Lee",

: "+15125550101",

: "12",

: null,

: [

"appointment"

]

: "2026-10-29T17:04:12.381Z",

: "2026-10-29T17:04:12.381Z"

}

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

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 instead.

openTime, closeTime and phoneNumber take the same formats as a location on Create a quote, 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

Authorization: Bearer <token>

Your sandbox API token. See Authentication.

Request body

application/json · required

addressobjectRequired
Address of this location
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

Responses

- dataobjectRequired
- warningsarray of objects