Overview
Welcome to the LADS Cloud API.
As an evolving product, we are continously
improving and updating our API.
All updates are completely backwards
compatible and only serve to enhance
the experience such as additional
features and higher resolution
error reporting.
We appreciate all questions and feedback at
support@ladsnet.com
The LADS Cloud API is an interface to the LADS Same-Day Delivery network of couriers that enables you to perform shipment related tasks such as request quotes, place new orders, and receive updates.
The LADS Cloud API is a RESTful based web service that consists of predictable, resource-oriented endpoints and uses standard HTTP features like verbs and response codes to indicate status and provide basic information on errors.
The LADS Cloud Connector provides an audit trail and insight into all of the requests you have made via the API. It also allows you to view your API keys and set webhook endpoints.
Requests
Base URL:
https://api.ladsnet.com/v1
The LADS Cloud API is REST-based. This means:
- It make use of standard HTTP verbs like
GET,POST,DELETE - The API uses standard HTTP responses to describe successes (
2xx) and errors (4xxand5xx). - All requests use standard query encoding. Payload data, if necessary, should be encoded as
application/x-www-form-urlencoded
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
Authentication
To authorize, use this code:
require 'uri'
require 'net/http'
url = URI("https://api.ladsnet.com/v1/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = 'lads_test_1234567890'
response = http.request(request)
puts response.read_body
import requests
url = "https://api.ladsnet.com/v1/"
headers = {
'X-API-KEY': "lads_test_1234567890"
}
response = requests.request("GET", url, headers=headers)
print(response.text)
# With shell, you can just pass the correct header with each request
curl "https://api-lads.net/v1/"
-H "X-API-Key: lads_test_1234567890"
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", () => {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.ladsnet.com/v1/");
xhr.setRequestHeader("X-API-KEY", "lads_test_1234567890");
xhr.send();
Make sure to replace
lads_test_1234567890with your API key.
Authenticate your requests by simply including your API key in the X-API-KEY header of each request.
To make the API easy to explore, every account has both test and live API keys. There is no switch or parameter for changing between live and test mode, just use the appropriate key. Requests made with test mode credentials never hit the courier network and incur no cost. For testing purposes, certain parameters are available to you that will respond with predictability for both successes and errors.
Authentication to the API is performed by including the X-API-KEY header key and your API key as its value.
Quotes
Create Quote
require 'uri'
require 'net/http'
url = URI("https://api.ladsnet.com/v1/quotes")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["x-api-key"] = 'lads_test_1234567890'
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&pieces=2&weight=55&carrier=cr_sd98u98sdf98sadf98as&service_level=next_day"
response = http.request(request)
puts response.read_body
import requests
url = "https://api.ladsnet.com/v1/quotes"
payload = "pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&pieces=2&weight=55&carrier=cr_sd98u98sdf98sadf98as&service_level=next_day"
headers = {
'x-api-key': "lads_test_8717465360423",
'Content-Type': "application/x-www-form-urlencoded",
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
curl -X POST \
https://api.ladsnet.com/v1/quotes \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'x-api-key: lads_test_1234567890' \
-d 'pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&pieces=2&weight=55&account=sh_sd98u98sdf98sadf98as&service_level=next_day'
const data = "pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&service_level=one_hour&pieces=2&weight=55&carrier=cr_sd98u98sdf98sadf98as";
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.ladsnet.com/v1/quotes");
xhr.setRequestHeader("x-api-key", "lads_test_1234567890");
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
xhr.send(data);
A successful response will contain a quote object
Before placing an order, you can first request a quote in order to ensure the desired pickup and delivery locations are supported by the LADS network and to get a price quote guaranteed for 24 hours.
HTTP Request
POST https://api.ladsnet.com/v1/quotes
Query Parameters
| Parameter | Description |
|---|---|
| account | The account ID of the customer requesting the shipment be delivered |
| carrier | The carrier ID of the courier you want to deliver the shipment |
| pickup_address | Pickup street address (i.e. 1600 Pennsylvania Ave) |
| pickup_postal_code | Pickup postal code (i.e. 20006) |
| delivery_address | Pickup street address |
| delivery_postal_code | Pickup postal code |
| pieces | Number of pieces in the shipment |
| weight | Total weight of the shipment in pounds |
| service_level | The service level (must be supported by the carrier) |
| accessorials | A string of accessorials for this delivery delimited by commas (ie 'guaranteed, cod_customs') |
Get Quote
require 'uri'
require 'net/http'
url = URI("https://api.ladsnet.com/v1/quotes/qt_wney4z9lz8w9ve4ye3d91yy4")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-api-key"] = 'lads_test_1234567890'
response = http.request(request)
puts response.read_body
import requests
url = "https://api.ladsnet.com/v1/quotes/qt_wney4z9lz8w9ve4ye3d91yy4"
headers = {
'x-api-key': "lads_test_1234567890"
}
response = requests.request("GET", url, headers=headers)
print(response.text)
curl -X GET \
https://api.ladsnet.com/v1/quotes/qt_wney4z9lz8w9ve4ye3d91yy4 \
-H 'x-api-key: lads_test_1234567890'
Const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.ladsnet.com/v1/quotes/qt_wney4z9lz8w9ve4ye3d91yy4");
xhr.setRequestHeader("x-api-key", "lads_test_1234567890");
xhr.send();
The above command returns a quote object:
{
"id": "qt_wney4z9lz8w9ve4ye3d91yy4",
"object": "quote",
"livemode": false,
"created": "2018-04-04T22:56:55.684Z",
"expires": "2018-04-05T22:56:55.684Z",
"carrier": "cr_sd98u98sdf98sadf98as",
"service_level": "next_day",
"fee": 1467,
"pickup_address": "700 Clark Ave, St. Louis, MO 63102, USA",
"delivery_address": "1401 Clark Ave, St. Louis, MO 63103, USA"
}
This endpoint retrieves a specific quote.
HTTP Request
GET https://api.ladsnet.com/v1/quotes/{ID}
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the quote to retrieve |
Quote Object
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the quote |
| object | string | Type of resource |
| livemode | boolean | True if a live API is used, else false |
| created | ISO 8601 | Datestamp when the quote was created |
| expires | ISO 8601 | Datestamp when the quote expires |
| carrier | string | ID of the carrier who is providing the quote |
| service_level | string | The service level of this quote |
| fee | integer | Total cost in cents |
| pickup_address | string | Fully formatted pickup address |
| delivery_address | string | Fully formatted delivery address |
Orders
Create Order
require 'uri'
require 'net/http'
url = URI("https://api.ladsnet.com/v1/orders")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = 'lads_test_1234567890'
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "pickup_name=John%20Doe&pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&pickup_phone=3148675309&delivery_name=Jane%20Doe&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&delivery_phone=6368675309&service_level=next_day&ready_at=2018-01-07T16%3A54%3A13Z&pieces=1&weight=5&customer_name=John%20Doe&customer_phone=3148675309&customer_email=john.doej%40gmail.com&carrier=cr_w5g59qk0mmr7pdnkrk0z887o"
response = http.request(request)
puts response.read_body
import requests
url = "https://api.ladsnet.com/v1/orders"
payload = "pickup_name=John%20Doe&pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&pickup_phone=3148675309&delivery_name=Jane%20Doe&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&delivery_phone=6368675309&service_level=next_day&ready_at=2018-01-07T16%3A54%3A13Z&pieces=1&weight=5&customer_name=John%20Doe&customer_phone=3148675309&customer_email=john.doej%40gmail.com&carrier=cr_w5g59qk0mmr7pdnkrk0z887o"
headers = {
'X-API-KEY': "lads_test_1234567890",
'Content-Type': "application/x-www-form-urlencoded"
}
response = requests.request("POST", url, data=payload, headers=headers)
print(response.text)
curl -X POST \
https://api.ladsnet.com/v1/orders \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'X-API-KEY: lads_test_1234567890' \
-d 'pickup_name=John%20Doe&pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&pickup_phone=3148675309&delivery_name=Jane%20Doe&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&delivery_phone=6368675309&service_level=next_day&ready_at=2018-01-07T16%3A54%3A13Z&pieces=1&weight=5&customer_name=John%20Doe&customer_phone=3148675309&customer_email=john.doej%40gmail.com&carrier=cr_w5g59qk0mmr7pdnkrk0z887o'
const data = "pickup_name=John%20Doe&pickup_address=700%20Clark%20Ave&pickup_postal_code=63102&pickup_phone=3148675309&delivery_name=Jane%20Doe&delivery_address=1401%20Clark%20Ave&delivery_postal_code=63103&delivery_phone=6368675309&service_level=next_day&ready_at=2018-01-07T16%3A54%3A13Z&pieces=1&weight=5&customer_name=John%20Doe&customer_phone=3148675309&customer_email=john.doej%40gmail.com&carrier=cr_w5g59qk0mmr7pdnkrk0z887o";
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.ladsnet.com/v1/orders");
xhr.setRequestHeader("X-API-KEY", "lads_test_1234567890");
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
xhr.send(data);
A successful response will contain an order object
Use this endpoint to place a new request to ship an order.
HTTP Request
POST https://api.ladsnet.com/v1/orders
Query Parameters
| Parameter | Description |
|---|---|
| carrier | The carrier ID of the courier you want to deliver the shipment |
| account | The account ID of the customer requesting the shipment be delivered |
| pickup_name | Name of pickup location |
| pickup_address | Pickup street address (i.e. 1600 Pennsylvania Ave) |
| pickup_postal_code | Pickup postal code (i.e. 20006) |
| pickup_phone | Phone number at pickup location |
| delivery_name | Name of delivery location |
| delivery_address | Delivery street address |
| delivery_postal_code | Delivery postal code |
| delivery_phone | Phone number at delivery location |
| pieces | Number of pieces in the shipment |
| weight | Total weight of the shipment in pounds |
| service_level | The service level (must be supported by the carrier) |
| ready_at | ISO 8601 formatted time of when the shipment will be ready for pickup (defaults to now if not specified) |
| customer_name | Name of the customer who placed the order |
| customer_phone | Phone number of the customer who placed the order |
| pickup_notifications | A list of emails to receive a notification when the order is picked up (delimited by commas) |
| delivery_notifications | A list of emails to receive a notification when the order is delivered (delimited by commas) |
| manifest | A description of the items |
| reference | A custom defined reference number to associate the shipment with an ID in your system |
| special_instructions | Special instructions for the carrier |
| pickup_tracking | The tracking number of the package to be picked up (such as an airbill number) |
| accessorials | A string of accessorials for this delivery delimited by commas (ie 'guaranteed, cod_customs') |
Get Order
require 'uri'
require 'net/http'
url = URI("https://api.ladsnet.com/v1/orders/or_56gl6jnzrzrnzg91eyj7p2nn")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["x-api-key"] = 'lads_test_1234567890'
response = http.request(request)
puts response.read_body
import requests
url = "https://api.ladsnet.com/v1/orders/or_56gl6jnzrzrnzg91eyj7p2nn"
headers = {
'x-api-key': "lads_test_1234567890"
}
response = requests.request("GET", url, headers=headers)
print(response.text)
curl -X GET \
https://api.ladsnet.com/v1/orders/or_56gl6jnzrzrnzg91eyj7p2nn \
-H 'x-api-key: lads_test_1234567890'
Const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.ladsnet.com/v1/orders/or_56gl6jnzrzrnzg91eyj7p2nn");
xhr.setRequestHeader("x-api-key", "lads_test_1234567890");
xhr.send();
The above command returns an order object:
{
"id": "or_56gl6jnzrzrnzg91eyj7p2nn",
"object": "order",
"livemode": false,
"created": "2018-04-04T23:25:26.998Z",
"updated": null,
"carrier": "cr_w5g59qk0mmr7pdnkrk0z887o",
"service_level": "next_day",
"status": "new",
"fee": 967,
"dispatch_id": 202001010001,
"dispatched": null,
"picked_up": null,
"delivered": null,
"pickup_eta": null,
"delivery_eta": null,
"ready_at": "2018-01-07T16:54:13.000Z",
"on_time": null,
"deadline": "2018-01-08T16:54:13.000Z",
"pod_name": null,
"pod_signature": null,
"pop_name": null,
"pop_signature": null,
"images": [],
"comments": [],
"reference": null,
"pickup_tracking": null,
"pickup": {
"name": "John Doe",
"phone:": null,
"address": "700 Clark Ave, St. Louis, MO 63102, USA",
"address_elements": {
"street": "700 Clark Ave",
"line2": null,
"city": "St. Louis",
"state": "MO",
"postal_code": "63102"
},
"location": {
"lat": 38.6226441,
"lng": -90.1928125
}
},
"delivery": {
"name": "Jane Doe",
"phone:": null,
"address": "1401 Clark Ave, St. Louis, MO 63103, USA",
"address_elements": {
"street": "1401 Clark Ave",
"line2": null,
"city": "St. Louis",
"state": "MO",
"postal_code": "63103"
},
"location": {
"lat": 38.626432,
"lng": -90.20261699999999
}
},
"customer": {
"name": "John Doe",
"phone": "3148675309"
},
"pickup_notifications": [],
"delivery_notifications": []
}
This endpoint retrieves a specific order.
HTTP Request
GET https://api.ladsnet.com/v1/orders/{ID}
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the order to retrieve |
Order Object
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the order |
| object | string | Type of resource |
| livemode | boolean | true if a live API is used, else false |
| created | ISO 8601 | Datestamp when the order was created |
| updated | ISO 8601 | Datestamp when the order was lasted updated |
| carrier | string | ID of the carrier delivering the order |
| service_level | string | The service level of this order |
| status | string | The status of the order (new dispatched picked_up or delivered) |
| fee | integer | Total cost in cents |
| dispatch_id | integer | A twelve digit id to be used if calling dispatch to identify the order |
| dispatched | ISO 8601 | Datestamp when the order was dispatched to the driver by the courier |
| picked_up | ISO 8601 | Datestamp when the order was picked up |
| delivered | ISO 8601 | Datestamp when the order was delivered |
| pickup_eta | ISO 8601 | Best guess datestamp when the order will be picked up (available when order status is dispatched and if supported by the carrier) |
| delivery_eta | ISO 8601 | Best guess datestamp when the order will be delivered (available starting when order status is dispatched and if supported by the carrier) |
| ready_at | ISO 8601 | Datestamp when the order will be available to be picked up |
| deadline | ISO 8601 | Datestamp when the order needs to be delivered as determined by the service_level |
| on_time | boolean | Whether the order is on track to be delivered before the deadline (available if delivery_eta is supported by the carrier) |
| pop_name | string | The Proof of Pickup name provided at the pickup location |
| pop_signature | string | A URL to an image that contains the Proof of Pickup signature provided at the pickup location |
| pod_name | string | The Proof of Delivery name provided at the delivery location |
| pod_signature | string | A URL to an image that contains the Proof of Delivery signature provided at the delivery location |
| images | array | An array of urls that contain images taken by the carrier (ie damaged parcels) |
| comments | array | An array of comments that contain extra information about the job (ie manifest, special instructions, pickup/delivery phone numbers) |
| reference | string | Customer reference number for this shipment |
| pickup_tracking | string | A custom tracking number of the shipment at the pickup location (such as an airbill number) |
| pickup | object | Location object of the pickup location |
| delivery | object | Location object of the delivery location |
| customer | object | Customer object |
| pickup_notifications | array | An array of emails to receive a notification when the order is picked up |
| delivery_notifications | array | An array of emails to receive a notification when the order is delivered |
Webhooks
The LADS Cloud API supports webhooks or POST notifications sent to your endpoint. Our webhooks support both https and http endpoints.
Webooks are notifications sent to your endpoint based upon triggers set in the LADS Cloud Connector. The triggers are configurable based on the status of the order. This means you can setup a trigger to receive a POST notification the moment an an order is Dispatched, Picked Up and/or Delivered.
Signature Signing
When an endpoint url is submitted on the LADS Cloud Connector Dashboard, a signature is automatically generated and displayed. This signature will be used in the LADS-Signature header for all subsequent responses. Use this secret signature to verify all incoming requests to your endpoint as genuine from the LADS Cloud API.
Available Notifications
The LADS Cloud API will trigger a POST notification to your endpoint on four separate occasions per order:
- When the order status changes from
newtodispatched - When the order status changes from
dispatchedtopicked_up - When the order status changes from
picked_uptodelivered - If the
on_timestatus changes
Each time a complete order object will be sent as a POST request to your endpoint.
Errors
The LADS Cloud API uses standard HTTP response codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed due to the information provided (e.g., a required parameter is missing or invalid), and codes in the 5xx range indicate an internal LADS error, please check out status page for potential outages if you're experiencing repeated 5xx range errors.
Due to vagueness in HTTP response codes, not all errors map cleanly (e.g., when a request is formed properly but the specified identifier doesn't exist). For greater clarity regarding why a request failed, please refer to the error message included in the response.
We use the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The resource requested is not retrievable with the given credentials. |
| 404 | Not Found -- The specified resource could not be found. |
| 405 | Method Not Allowed -- You tried to access a resource with an invalid method. |
| 429 | Too Many Requests -- You're requesting too often! Please slow down. |
| 5xx | Internal Server Error -- Something went wrong on our end. Check out status page if you are experiencing these repeatedly |