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 |
| "" | 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:
{
"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
- Stop Progress WebHook
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. |