Address book

Address books allow you to keep a library of locations to use within Shipments. Locations added to an address book can be copied into the stops parameter when creating a new shipment.

Before you begin

Get a list of address book entries

curl --location --request GET 'https://sandbox-api.shipwell.com/v2/address-book/' \
--header 'Authorization: Token {user-token}'

The GET v2/address-book returns a list of all current address book entries. By default, the response returns one page of 30 address book entries in ascending(+) order based on the date of the creation. Change the value of the page and page-size parameters to return more pages and address book entries.

In the response, each address book contains a unique id used to pull, update, or delete that specific location using the GET address book id endpoint. The address book appears at the top of the address book entry.

Create a new address book entry

To create a new address book entry, use the POST v2/address-book endpoint. New address book entries have very similar minimum requirements to a shipment stop. Any new address book entries extend to both the API and Shipwell UI.

Example Request

curl --location --request POST 'https://sandbox-api.shipwell.com/v2/address-book/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <user-token>' \
--data-raw '{
    "address": {
        "company_name": "Shipwell",
        "address_1": "550 Congress Ave",
        "address_2": "550",
        "city": "Austin",
        "country": "US",
        "latitude": 36566298.34978154,
        "longitude": 83294741.83434466,
        "phone_number": "512-555-3100",
        "postal_code": "78752",
        "state_province": "TX",
        "timezone": "CST"
    },
    "is_default_origin": "true",
    "location_name": "Shipwell Inc",
    "location_type": {
        "name": "Business (with dock or forklift)",
        "id": 1
    },
    "point_of_contacts": [
        {
                    "first_name": "Ishan",
                    "last_name": "Kumar",
                    "job_title": "User",
                    "phone_number": "+15123430003",
                    "email": "ishan+sandbox@gmail.com",
                    "preferences": {
                        "cancellation": false,
                        "delayed": false,
                        "delivered": false,
                        "eta_changed": false,
                        "picked_up": true,
                        "receive_bol_on_shipment_booked": false,
                        "shipment_booked": false
                    
            }
        }  
    ]
}'

Step One: Address

Enter the following parameters under the address data category. These parameters are required in order for a new address book entry to be accepted.

  • company-name: The name of the company that owns the location
  • address_1: The street number and street name of the location. Add address_2 to account for suite or apartment numbers
  • city: The city listed in the address
  • country: The country of the address. Must use a two-letter identifier, such as US for the United States
  • phone_number: Phone number for the business
  • postal_code: The postal code for which the business is located
  • state_province: The state where the address is located. Must use a two-letter identifier, such as TX for Texas.
  • timezone: The timezone, such as CST, that the location follows

    "address": {
        "company_name": "Shipwell",
        "address_1": "550 Congress Ave",
        "address_2": "550",
        "city": "Austin",
        "country": "US",
        "latitude": 36566298.34978154,
        "longitude": 83294741.83434466,
        "phone_number": "512-555-3100",
        "postal_code": "78752",
        "state_province": "TX",
        "timezone": "CST"
    },

Step Two: Point of contacts

Add one or multiple points of contact to your address book entry. Remember to account for that point of contact's email preferences for shipment updates, as indicated by the booleans at the end of the following example:

   "point_of_contacts": [
        {
                    "first_name": "Ishan",
                    "last_name": "Kumar",
                    "job_title": "User",
                    "phone_number": "+15123430003",
                    "email": "ishan+sandbox@gmail.com",
                    "preferences": {
                        "cancellation": false,
                        "delayed": false,
                        "delivered": false,
                        "eta_changed": false,
                        "picked_up": true,
                        "receive_bol_on_shipment_booked": false,
                        "shipment_booked": false
                    
            }
        }  
    ]

Step Three: Location name and type

Lastly, enter the following parameters before entering in your new address book entry request:

is_default_origin: A boolean that indicates whether the location is used for the origin of a shipment location_name: A unique name for the location location_type: The type of location. To find a list of location ids, see Location type

 "is_default_origin": "true",
 "location_name": "Shipwell Inc",
 "location_type": {
        "name": "Business (with dock or forklift)",
        "id": 1

Step Four: Response

Send all of the necessary data entered into the body of the request using cURL or Postman. Upon completion Shipwell's returns a YAML response.

{
    "id": "03465c9e-2a4b-414c-be25-2630e09fd4ba",
    "location_name": "Shipwell Inc",
    "dock_hours_start": null,
    "dock_hours_end": null,
    "notes": null,
    "address": {
        "id": "17fa1f4f-3b90-4ca4-971e-371f846b540f",
        "address_1": "550 Congress Ave",
        "address_2": "550",
        "city": "Austin",
        "state_province": "TX",
        "postal_code": "78752",
        "country": "US",
        "phone_number": "+15125553100",
        "latitude": 36566298.34978154,
        "longitude": 83294741.83434466,
        "timezone": "CST",
        "formatted_address": "550 Congress Ave 550, Austin, TX 78752, US",
        "created_at": "2020-09-10T15:44:46.109893Z",
        "updated_at": "2020-09-10T15:44:46.111194Z"
    },
    "point_of_contacts": [
        {
            "id": "6cca54c3-baa4-466a-974b-3b3bb2ca835e",
            "first_name": "Ishan",
            "last_name": "Kumar",
            "job_title": "User",
            "phone_number": "+15123430003",
            "email": "ishan+sandbox@gmail.com",
            "preferences": {
                "cancellation": false,
                "delayed": false,
                "delivered": false,
                "eta_changed": false,
                "picked_up": true,
                "receive_bol_on_shipment_booked": false,
                "shipment_booked": false
            },
            "created_at": "2020-09-10T15:44:46.123300Z",
            "updated_at": "2020-09-10T15:44:46.131231Z"
        }
    ],
    "location_type": {
        "id": 1,
        "name": "Business (with dock or forklift)"
    },
    "created_at": "2020-09-10T15:44:46.120491Z",
    "updated_at": "2020-09-10T15:44:46.121757Z",
    "company_name": null,
    "is_default_origin": true,
    "accessorials": [],
    "external_reference": null,
    "default_appointment_type": null,
    "dock_external_id": null
}

Delete and update an address book entry

Delete or update an address book using an address book id. The address book appears at the top of the address book entry.

Update

Add any parameters you wish to add or change into the request body. Make sure to copy all already entered request fields. In the following request shows the addition of the dock_hours_start and dock_hours_end parameters

curl --location --request PUT 'https://sandbox-api.shipwell.com/v2/address-book/03465c9e-2a4b-414c-be25-2630e09fd4ba/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <user-token>' \
--data-raw '{
    "address": {
        "company_name": "Shipwell",
        "address_1": "550 Congress Ave",
        "address_2": "550",
        "city": "Austin",
        "country": "US",
        "latitude": 36566298.34978154,
        "longitude": 83294741.83434466,
        "phone_number": "512-555-3100",
        "postal_code": "78752",
        "state_province": "TX",
        "timezone": "CST"
    },
    "dock_hours_start": "08:00:00",
    "dock_hours_end": "18:00:00",
    "is_default_origin": "true",
    "location_name": "Shipwell Inc",
    "location_type": {
        "name": "Business (with dock or forklift)",
        "id": 1
    },
    "point_of_contacts": [
        {
                    "first_name": "Ishan",
                    "last_name": "Kumar",
                    "job_title": "User",
                    "phone_number": "+15123430003",
                    "email": "ishan+sandbox@gmail.com",
                    "preferences": {
                        "cancellation": false,
                        "delayed": false,
                        "delivered": false,
                        "eta_changed": false,
                        "picked_up": true,
                        "receive_bol_on_shipment_booked": false,
                        "shipment_booked": false
                    
            }
        }  
    ]
}'

Delete

Use the address book id to delete an address book entry.

curl --location --request DELETE 'https://sandbox-api.shipwell.com/v2/address-book/03465c9e-2a4b-414c-be25-2630e09fd4ba/' \
--header 'Authorization: Token <user-token>'

The Shipwell API does not return a response when deleting an address book entry. Validate the deletion by using the GET v2/address-book/addressBookid endpoint.

Get address book id request

curl --location --request GET 'https://sandbox-api.shipwell.com/v2/address-book/03465c9e-2a4b-414c-be25-2630e09fd4ba/' \
--header 'Authorization: Token <user-token>'

Validate deletion response

{
    "error": "NotFound",
    "error_description": "Not found."
}
Copyright © Shipwell 2020. All right reserved.