Introduction

Greetings from the Upper team!

We are pleased to give you our API access to help you do better with daily delivery operations. Integrate any application with ease, and let the automated software collect your data before you go on to plan and optimize routes using Upper’s advanced features.

Basically, the API (Application Programming Interface) allows you to transfer the data from one system to another one. For such seamless data transfer, we have enabled API integration for the business owners like you.

So, whenever you need the data such as addresses, start time, end time, contact name, email, personal note, etc, you can get them with the help of an API token. In short, you will be able to get the necessary parameters to the route planner from any existing system.

The REST API supports multiple languages which means it works with systems using PHP, Go, Erland, cURL (using cmd and Bash), Perl, VB.NET, VBScript, Java, Python, Node, C++, or C#. So, why wait? Connect with multiple systems using your API key.

Got questions or suggestions for us? Why not get in touch with us at [email protected].

Authentication

Business owners having access to API can find the key from profile > settings > WS API. Or else, simply follow the link (https://crew.upperinc.com/setting).

Our team looks forward to handing over an API key in order to help you perform quick route optimization. Below is how does it look like:

x-api-token: {{API TOKEN}}

Admin API'S

Create Route Stop

curl --location -g --request POST '{{base_url}}addDeliveryTask' \
                  --header 'x-api-token: api_token' \
                  --header 'Content-Type: application/x-www-form-urlencoded' \
                   --data-urlencode 'customer_system_id=4a9c8a18-f628-4f1c-9833-8a85cda9b2e3' \
                        --data-urlencode 'address=6460 S Dixie Hwy, South Miami, Florida' \
                        --data-urlencode 'start_time=10:00:00' \
                        --data-urlencode 'end_time=12:00:00' \
                        --data-urlencode 'contact_name=John' \
                        --data-urlencode 'phone_number=(305) 661-0778' \
                        --data-urlencode '[email protected]' \
                        --data-urlencode 'note=note' \
                        --data-urlencode 'city=South Miami' \
                        --data-urlencode 'state=Florida' \
                        --data-urlencode 'country=United States' \
                        --data-urlencode 'zipcode=33143' \
                        --data-urlencode 'latitude=25.696858' \
                        --data-urlencode 'longitude=-80.298168' \
                        --data-urlencode 'company_name=Kathryne Company' \
                        --data-urlencode 'stop_type=Delivery' \
                        --data-urlencode 'stop_priority=High' \
                        --data-urlencode 'parcel_count=' \
                        --data-urlencode 'stop_duration=' \
                        --data-urlencode 'custom1=custom_field_1_value' \
                        --data-urlencode 'custom2=custom_field_2_value' \
                        --data-urlencode 'custom3=custom_field_3_value' \
                        --data-urlencode 'custom4=custom_field_4_value' \
                        --data-urlencode 'custom5=custom_field_5_value'

The above command returns JSON structured like this:

{
               "response_status": "1",
               "message": "success"
            }
            

This endpoint create route stop.

HTTP Request

POST {{base_url}}addDeliveryTask

Header Parameters

Parameter Default Description Required
x-api-token "" api_token Yes

Query Parameters

Parameter Default Description Required
customer_system_id "" Your system generated id for the order No
address "" The Address #1 and/or Address #2 of the stop. Yes
start_time "" The start time for this stop's time window constraint. No
end_time "" The end time for this stop's time window constraint. No
contact_name "" The name of the stop, typically your customer’s name. No
phone_number "" The phone number of the stop, typically your customer’s phone number to allow the driver to call them or send an SMS. No
email "" The email of the stop, typically your customer’s email. No
note "" The optional note that will accompany the driver’s instructions. Notes do not affect the optimization process. A free form string. No
city "" The city of the stop. No
state "" The state/province of the stop. No
country "" The country of the stop. No
zipcode "" The zip code of the stop. No
latitude "" The latitude of the stop. No
longitude "" The longitude of the stop. No
company_name "" Typically customer's business name of the stop. No
stop_type "" (Delivery/Pickup) No
stop_priority "" (Normal/Urgent/Crucial/High/Medium/Low) No
parcel_count "" Parcel Count No
stop_duration "" Stay at stop No
custom1 "" Custom Field 1 value No
custom2 "" Custom Field 2 value No
custom3 "" Custom Field 3 value No
custom4 "" Custom Field 4 value No
custom5 "" Custom Field 5 value No

Get Stop Details

curl --location -g --request GET '{{base_url}}getStopDetail?stop_id=6460' \
            --header 'x-api-token: api_token' \
            
            
            
            

The above command returns JSON structured like this:

{
               "response_status": "1",
               "message": "Stop Details data successfully get"
               "data":{
               "id": "6460",
               "driver_name": "Driver 1",
               "route_name": "Route 11",
               "stop_status": "None",
               "address": "6460 S Dixie Hwy, South Miami, Florida",
               "latitude": "25.696858",
               "longitude": "-80.298168",
               "contact_name": "John",
               "company_name": "Kathryne Company",
               "phone": "(305) 661-0778",
               "email": "[email protected]",
               "note": "note",
               "city": "South Miami",
               "state": "Florida",
               "country": "United States",
               "zipcode": "33143",
               "earliest_time": "10:00:00",
               "latest_time": "12:00:00",
               "stop_type": "Delivery",
               }    
}
               

This endpoint will return stop details which you have added in Add Delivery Task API.

HTTP Request

GET {{base_url}}getStopDetail

Header Parameters

Parameter Default Description Required
x-api-token "" api_token Yes

Query Parameters

Parameter Default Description Required
stop_id "" Stop ID of Delivery Task Yes

Get Routes

curl --location -g --request GET '{{base_url}}getRoutes?from_date=2023-05-17&to_date=2023-05-17&route_name=2&assigned_drivers=john&route_status=Dispatch&min_stops=4&max_stops=15' \
            --header 'x-api-token: api_token' \
            
            
            
            

The above command returns JSON structured like this:

{
    "code": "200",
    "message": "Data get successfully"
    "data":[
      {
    "id": "29314",
    "route_name": "Florida Delivery",
    "route_date": "2022-08-10",
    "assigned_drivers": "Nicole D. Joshua",
    "route_status": "Dispatch",
    "stop_duration": 900,
    "optimization_preference": "Time",
    "unit": "Miles",
    "drive_preference": "7",
    "vehicle": "Small Truck",
    "navigation_map": "Apple",
    "trafic_consider": "N",
    "curbside": null,
    "pickup_delivery": "Auto",
    "total_stops": 4,
    "total_drivers": 1,
    "total_time": 3123,
    "total_service_time": 3600,
    "total_distance": 33308,
    "total_delivered_stops": 0,
    "total_missed_stops": 0
    },    
    {
    "id": "29317",
    "route_name": "Southwest Delivery",
    "route_date": "2022-08-10",
    "assigned_drivers": "",
    "route_status": "Upcoming",
    "stop_duration": 900,
    "optimization_preference": "Time",
    "unit": "Miles",
    "drive_preference": "7",
    "vehicle": "Small Truck",
    "navigation_map": "Apple",
    "trafic_consider": "N",
    "curbside": null,
    "pickup_delivery": "Auto",
    "total_stops": 4,
    "total_drivers": 0,
    "total_time": null,
    "total_service_time": null,
    "total_distance": null,
    "total_delivered_stops": 0,
    "total_missed_stops": 0
    }  
    ]  
}


    

This endpoint will return the list of routes specific to the filters applied through query parameters.

To fetch the list of routes of a date or range of dates, the values of the query parameters from_date and to_date, both will have to be specified to get the list of routes.

If none of the query parameters are set, then the api will return the list of routes of the current date.

HTTP Request

GET {{base_url}}getRoutes

Header Parameters

Parameter Default Description Required
x-api-token "" api_token Yes

Query Parameters

Parameter Default Description Required
from_date "" Start date of routes
(YYYY-MM-DD)
No
to_date "" End date of routes
(YYYY-MM-DD)
No
route_name "" Name of route No
assigned_drivers "" Comma(,) separated names of assigned drivers No
route_status "" Route statuses:
Draft (Upcoming routes)
Active (Routes in transit)
Dispatch (Routes that are dispatched or ready for dispatch)
Complete (Completed routes)
No
min_stops "" Minimum number of stops No
max_stops "" Maximum number of stops No

Get Route Stop

curl --location -g --request GET '{{base_url}}getRouteStop?route_id=29314' \
            --header 'x-api-token: api_token' \
            
            
            
            

The above command returns JSON structured like this:

{
      "code": "200",
      "message": "Data get successfully"
      "data":[
        {
         "id": "9085",
         "driver": "Nicole D. Joshua",
         "v_email": "[email protected]",
         "v_contact": "644621340",
         "country":  "France",
         "total_distance":  90848,
         "total_time":  8635,
         "v_company_logo_thumb":  null,
         "v_image_thumb":  null,
         "route_stops":  [
            {
               "id":  990667,
               "i_user_id":  9085,
               "stop_status":  "None",
               "address":  "Silver Vase, Southwest 217th Avenue, Homestead, FL, USA",
               "latitude":  "25.5209428",
               "longitude":  "-80.5417392",
               "address_type":  "Start",
               "stop_order":  -1,
               "contact_name":  "",
               "company_name":  "",
               "phone":  "",
               "email":  "",
               "note":  "",
               "city":  "Miami-Dade County",
               "state":  "Florida",
               "country":  "United States",
               "zipcode":  "33031",
               "earliest_time":  null,
               "latest_time":  null,
               "parcel_place":  null,
               "stop_type":  null,
               "start_time":  null,
               "arrival_time":  null,
               "arrival_status":  "None",
               "custom1":  null,
               "custom2":  null,
               "custom3":  null,
               "custom4":  null,
               "custom5":  null,
               "stop_log":  null,
               "parcel_images":  []
            },
            {
               "id":  990595,
               "i_user_id":  9085,
               "stop_status":  "None",
               "address":  "Copper's Nursery, Inc., Southwest 312th Street, Homestead, FL, USA",
               "latitude":  "25.4767829",
               "longitude":  "-80.5471029",
               "address_type":  "Stop",
               "stop_order":  1,
               "contact_name":  "Miceal Clark",
               "company_name":  "Miceal Inc",
               "phone":  "",
               "email":  "[email protected]",
               "note":  "Florida city flower delivery - St 3rd, House no. 7",
               "city":  "Miami-Dade County",
               "state":  "Florida",
               "country":  "United States",
               "zipcode":  "33030",
               "earliest_time":  null,
               "latest_time":  null,
               "parcel_place":  null,
               "stop_type":  null,
               "start_time":  null,
               "arrival_time":  null,
               "arrival_status":  "None",
               "custom1":  "",
               "custom2":  "",
               "custom3":  "",
               "custom4":  "",
               "custom5":  "",
               "stop_log":  null,
               "parcel_images":  [ 
                  {
                     "id":  520,
                     "i_route_stop_id":  990595,
                     "v_image":  "https://uprt.cc/img/cGFyY2VsLTUyMA=="
                  }
               ],
               "customer_notes":  [] 
            },
            {
               "id":  990594 ,
               "i_user_id":  9085 ,
               "stop_status":  "None" ,
               "address":  "Homestead, FL, USA" ,
               "latitude":  "25.4687224" ,
               "longitude":  "-80.4775569" ,
               "address_type":  "Stop" ,
               "stop_order":  2 ,
               "contact_name":  "" ,
               "company_name":  "" ,
               "phone":  "" ,
               "email":  "" ,
               "note":  "" ,
               "city":  "Miami-Dade County" ,
               "state":  "Florida" ,
               "country":  "United States" ,
               "zipcode":  "" ,
               "earliest_time":  null ,
               "latest_time":  null ,
               "parcel_place":  null ,
               "stop_type":  null ,
               "start_time":  null ,
               "arrival_time":  null ,
               "arrival_status":  "None" ,
               "custom1":  "",
               "custom2":  "",
               "custom3":  "",
               "custom4":  "",
               "custom5":  "",
               "stop_log":  null,
               "parcel_images":  [ 
                  {
                     "id":  519,
                     "i_route_stop_id":  990594,
                     "v_image":  "https://uprt.cc/img/cGFyY2VsLTUxOQ=="
                  }
               ],
               "customer_notes":  [] 
            },
            {
               "id":  990668,
               "i_user_id":  9085,
               "stop_status":  "None",
               "address":  "Henry's Range, Southwest 228th Avenue, Homestead, FL, USA",
               "latitude":  "25.4704514",
               "longitude":  "-80.56198909999999",
               "address_type":  "End",
               "stop_order":  -1,
               "contact_name":  "",
               "company_name":  "",
               "phone":  "",
               "email":  "",
               "note":  "",
               "city":  "Miami-Dade County",
               "state":  "Florida",
               "country":  "United States",
               "zipcode":  "33030",
               "earliest_time":  null,
               "latest_time":  null,
               "parcel_place":  null,
               "stop_type":  null,
               "start_time":  null,
               "arrival_time":  null,
               "arrival_status":  "None",
               "custom1":  null,
               "custom2":  null,
               "custom3":  null,
               "custom4":  null,
               "custom5":  null,
               "stop_log":  null,
               "parcel_images":  [],
               "customer_notes":  []
            }
         ] 
      }
   ] 
}
  
  
      

This endpoint will return the route’s detail by ID.

HTTP Request

GET {{base_url}}getRouteStop

Header Parameters

Parameter Default Description Required
x-api-token "" api_token Yes

Query Parameters

Parameter Default Description Required
route_id "" ID of particular route Yes

WebHooks

Upper Route Planner allows you to use webhook we can notify you about the events. You can register a new webhook at our platform ("https://crew.upperinc.com/setting").

Headers:

client-secret: (Secret token which we will send you on a private channel)

Body Payload:

Copy to Clipboard
{ "event": "stop.updated", "data":[ { "customer_system_id": "1074f73a-b6d0-44c2-8d04-70745d8d5d7c", "id": "990668", "stop_status": "None", "address": "Copper's Nursery, Inc., Southwest 312th Street, Homestead, FL, USA", "latitude": "25.4767829", "longitude": "-80.5471029", "address_type": "Stop", "stop_order": 1, "contact_name": "Miceal Clark", "company_name": "Miceal Inc", "phone": "+16465780322", "email": "[email protected]", "note": "Florida city flower delivery - St 3rd, House no. 7", "city": "Miami-Dade County", "state": "Florida", "country": "United States", "zipcode": "33030", "earliest_time": "10:00:00", "latest_time": "11:20:00", "stop_type": "Delivery", "start_time": "2022-10-17 09:10:00", "arrival_time": "2022-10-17 10:40:45", "arrival_status": "Arrived", "custom1": "00295-33390", "custom2": "Prepaid", "custom3": "", "custom4": "", "custom5": "", "parcel_images": [ { "id": "529", "image": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=live/parcel_img/634d867d60172172966422.png", "thumb_image": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=live/parcel_img/thumb/live/parcel_img/634d867d60172172966422.png" }, { "id": "550", "image": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=live/parcel_img/634d8698d0517030727122.png", "thumb_image": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=live/parcel_img/thumb/live/parcel_img/634d8698d0517030727122.png" } ], "customer_notes": [ { "id": 222, "note": "Please take the stairs as the lift is not working" } ], "stop_log": { "id": "21913", "log_status": "2022-10-17 10:40:45", "log_time": "Success", "reason": "Delivered as per instructions", "delivery_note": "Dropped at the front door", "team_note": null, "other_note": null, "signature_image_path": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=dev/routestoplog/634d8725f3195196950879.png", "server_image_path": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=live/parcel_img/634d8698d0517030727122.png", "signature_image_path_thumb": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=dev/routestoplog/thumb/634d8725f3195196950879.png", "server_image_path_thumb": "https://q1umjlznsd.execute-api.us-west-2.amazonaws.com/get-image-uppercrew-prod?objectKey=live/parcel_img/thumb/634d8698d0517030727122.png" } } ] }

Events

Errors

The Upper Route Planner API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified request could not be found.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.