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

Your user token used for the Authorization header. To see how to find your user token, follow the instructions on the Authentication page.
Create your first shipment .

Get a list of address book entries

Copy

Copied

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

Copy

Copied

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

Copy

Copied

"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:

Copy

Copied

   "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

Copy

Copied

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

Copy

Copied

{
    "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

Copy

Copied

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.

Copy

Copied

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

Copy

Copied

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

Copy

Copied

{
    "error": "NotFound",
    "error_description": "Not found."
}