Introduction

Waybill.work® exposes its data via an Application Programming Interface (API), so developers can interact in a programmatic way with the waybill application. This document is the official reference for that functionality.

API Resources

All API URLs listed in this documentation are relative to http://{your-custom-domain-url}/. For example, the /api/addresses/ resource is reachable at http://{your-custom-domain-url}/api/addresses.

Authentication

The API requires Waybill.work® token HTTP Authentication with your Shippo token (live or test). In order to authenticate properly, please put Authorization: Bearer <API_TOKEN> in your header. You can find your token on the customer account settings page.

For more information about authentication and test mode, please visit our Authentication guide.

The API is available via Secure Socket Layer (SSL) only. Insecure attempts to access the API will return HTTP status 403/Forbidden.

Request & Response Data

Request data is passed to the API by POSTing JSON objects with the appropriate key/value-pairs to the respective resource. The documentation for each API resource contains more details on the values accepted by a given resource.

Response data also formatted as JSON object. You can specify how many results per page are to be returned. For instance, /rates/?results=25 will return up to 25 results.

REST & Disposable Objects

The Shippo API is built around REST principles. Use POST requests to create objects, GET requests to retrieve objects, and PUT requests to update objects.

Only the Accounts object can be updated via PUT requests. All other objects such as Addresses, Parcels, Shipments, Rates are disposable. This means that once you have created an object, you cannot change it. Instead, create a new one with the desired values.

Description

Before you can start using the Waybill.work® API, you’ll need to register for a customer account and get your API live token from the API page of the dashboard.

http://{your-custom-domain-url}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Request / Response Formats

All Waybill.work® APIs support an optional return format parameter format=json. Note that json is the default response format. Some endpoints also support a simple txt format.

  • HTTP Response Status Code is 200 on all valid response in json and xml formats. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid.

  • For txt format calls, the HTTP Response Status Codes are used to indicate a problem with the request, rate limiting, or other errors. The response body will be equivalent to status_txt in json and xml calls for all non 200 response codes.

  • The status_code is 200 for a successful request, 403 when rate limited, 503 for temporary unavailability, 404 to indicate not-found responses, and 400 for all other invalid requests or responses.

  • status_txt will be a value that describes the nature of any error encountered. Common values are RATE_LIMIT_EXCEEDED, MISSING_ARG_%s to denote a missing URL parameter, and INVALID_%s to denote an invalid value in a request parameter (where %s is substituted with the name of the request parameter).

  • If the status_code is not 200, only status_code and status_txt are guaranteed to be present and valid.

Description
All API requests should be against the domain http://{your-custom-domain-url}
                        
Headers
Authorization : Bearer {AccessToken}
Accept : Application/json
GET / POST
http://{your-custom-domain-url}/api/{method}
Response
{ "status_code": 200, "status_txt": "OK", "data" : ... }
{ "status_code": 400, "status_txt": "MISSING_ARG_LOGIN"}
{ "status_code": 403, "status_txt": "Unauthorized"}
{ "status_code": 500, "status_txt": "Internal Error"}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

CORS or Cross Origin Resource Sharing

The Waybill.work® API supports CORS, or Cross Origin Resource Sharing.

Historically, Javascript AJAX requests were restricted to a same domain origin policy. This meant that your website at http://mysite.com/ could not make AJAX requests to http://{your-custom-domain-url}/, since they were not the same domain.

With the introduction of HTML5 and advancements in modern browsers, CORS allows website owners to control who can access data via Javascript AJAX requests. In this way, CORS functions like Flash's Cross Domain Origin Policy. The latest version of the Waybill.work® API (V3) supports CORS requests from any domain.

Here is some basic example Javascript to get you started:

You can also read more about CORS here.

Description
var http_request;
http_request = new XMLHTTPRequest();
http_request.open("POST", "https://{your-domain}.wabill.work");
http_request.setRequestHeader("Content-Type", "application/json");

Authentication

Waybill.work makes it easy to perform authentication via traditional login forms, but what about APIs? APIs typically use tokens to authenticate users and do not maintain session state between requests. Waybill makes API authentication a breeze using Oauth mechanism, which provides a full OAuth2 server implementation for your mobile application in a matter of minutes.

This documentation assumes you are already familiar with OAuth2. If you do not know anything about OAuth2, consider familiarizing yourself with the general terminology and features of OAuth2 before continuing.

Request Access Token

The Waybill.work allows your other first-party clients, such as a mobile application, to obtain an access token using an e-mail address / username and password. This allows you to issue access tokens securely to your first-party clients without requiring your users to go through the entire OAuth2 authorization code redirect flow. This documentation assumes you are already familiar with OAuth2 token based authendication system. If you do not know anything about bearer tokens, consider familiarizing yourself with the general terminology and features of Bearer tokens before continuing.

http://{your-custom-domain-url}/api/account/login

Param Description
email Email address of the account holder.
password Password of the account holder.
Authentication Status
200 - Success Authendication successful and token generated.
403 - Failed Authendication failed and invalid request.
Post Request
http://{your-custom-domain-url}/api/account/login
Post Params
email
password
Response
{
"status":"success",
"access_token":""
}

Revoke Access Token

Sometimes, your users may want to revoke access tokens to themselves without going through the typical logout flow. Allowing users to revoke tokens to themselves via your application's UI can be useful for allowing users to experiment with your API or may serve as a simpler approach to revoke access tokens in general.

http://{your-custom-domain-url}/api/account/logout

Authorization: Bearer {access_token}
Accept: application/json
Authentication Status
200 - Success Revoke token successful and token removed.
403 - Failed Authendication failed and invalid request.
GET Request
http://{your-custom-domain-url}/api/account/logout
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Shipments

The /shipments endpoint allows you to load shipments from your account to the Waybill.work dashboard and to create, retrieve, list, and manage shipments programmatically. You can also retrieve shipping rates, shipping labels, and track shipments for each shipment.

There are a few things to be aware of when testing the Shipments endpoint. For starters, you want to be sure that you’re using your customer token for authenticating your requests, to ensure that all orders are being created in request mode. Additionally, test shipments will display in the Waybill.work dashboard and you can only retrieve them via the API using your token.

GET - http://{your-custom-domain-url}/api/shipments

Authorization: Bearer {access_token}
Accept: application/json
Endpoint
http://{your-custom-domain-url}/api/shipments
GET Request
http://{your-custom-domain-url}/api/shipments
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success",
"shipments": "[...]"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Fetch Shipment

You can fetch an shipment with all the information about your shipment by sending a GET request to the /shipment/{id} endpoint. An shipment typically consists of the all information.

Endpoint
http://{your-custom-domain-url}/api/shipment/{id}
GET Request
http://{your-custom-domain-url}/api/shipment/{id}
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success",
"shipment": "[...]"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Update Shipment

You can update an shipment with all the information you have access to by sending a POST request to the /shipment/{id}/update endpoint. An shipment update request typically consists of the information which required to update.

Shipment update
/api/shipment/{id}

Add more product
/api/shipment/{id}/addproduct

Update product
POST /api/shipment/{id}/product/{id}/update

Delete product
GET /api/shipment/{id}/product/{id}/delete

Add more comment
POST /api/shipment/{id}/addcomment

Delete comment
GET /api/shipment/{id}/comment/{id}/delete

Endpoint
/api/shipment/{id}/update
POST Request
http://{your-custom-domain-url}/api/shipment/{id}/update
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Cancel Shipment

You can cancel an shipment by sending a GET request to the /shipment/{id}/cancel endpoint.

Shipment cancellation
/api/shipment/{id}/cancel

Endpoint
/api/shipment/{id}/cancel
POST Request
http://{your-custom-domain-url}/api/shipment/{id}/cancel
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Tracking Shipment

Tracking API allows you to track shipments with normalized data, full tracking history and real-time updates. When combined with webhooks, you will get push-style notifications anytime a tracking update occurs. This powerful combination allows you to always know what the latest tracking information is across all of your shipments and if a recipient may need to take action to retrieve their shipment in a single service.

Endpoint
/api/track

Post params
tracking_type : tracking_no/reference_no shipment_id : {number}
Endpoint
/api/track
POST Request
http://{your-custom-domain-url}/api/track
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"shipment": "{...}"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Book Shipment

You can create an shipment request with all the information about your shipment by sending a POST request to the /shipment/create endpoint. An shipment typically consists of the following information:

Sender information
  • sender_name
  • sender_email
  • sender_street_address
  • sender_city
  • sender_state
  • sender_country
Receiver information
  • receiver_name
  • receiver_email
  • receiver_street_address
  • receiver_city
  • receiver_state
  • receiver_country
Product information
  • product_name[]
  • product_weight[]
  • product_value[]
  • product_quantity[]
Shipment information
  • shipping_mode
  • shipment_type
  • weight
  • comments
Endpoint
http://{your-custom-domain-url}/api/shipment/create
POST Request
http://{your-custom-domain-url}/api/shipment/create
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success",
"shipment": "[...]"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Resources

Resources endpoints provides various type of datas available to the API client. This includes zone finder, rate calculator shipping rules and charge estimation and much more by sending GET/POST requests to the /resource endpoint. An resource request typically consists of the following additional endpoints:

Shipping Rates
  • /api/resource/rate
Shipping Rules
  • /api/rosource/rules
Additional charges & Taxes
  • /api/resource/taxes-and-discounts
Shipment options
  • /api/resource/options/{option_type}
Endpoint
http://{your-custom-domain-url}/api/resource/{type}
POST Request
http://{your-custom-domain-url}/api/resource/{type}
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success",
"data": "[...]"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Delivery Shipments

/api/shipments/delivery endpoint returns all the assigned shipments to the driver account for delivery to the API client. This response includes all the shipment details which required to do the delivery, by sending GET requests to the /api/shipments/delivery endpoint.

Delivery Shipments
  • /api/shipments/delivery
Endpoint
http://{your-custom-domain-url}/api/shipments/delivery
POST Request
http://{your-custom-domain-url}/api/shipments/delivery
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success",
"shipments": "[...]"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Pickup Requests

/api/shipments/pickup endpoint returns all the assigned shipments to the driver account for pickup to the API client. This response includes all the shipment details which required to do the delivery, by sending GET requests to the /api/shipments/pickup endpoint.

Pickup Requests
  • /api/shipments/pickup
Endpoint
http://{your-custom-domain-url}/api/shipments/pickup
POST Request
http://{your-custom-domain-url}/api/shipments/pickup
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success",
"shipments": "[...]"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Update Status

/api/shipment/{id}/addstatus endpoint used to update the status of the shipment by sending POST requests to the /api/shipment/{id}/addstatus endpoint.

Status Update
  • /api/shipment/{id}/addstatus
Status Params
Param Description
date_time DD-MM-YYYY HH:MM:SS
status Status of the shipment.
location Current location of the shipmment
remarks (optional) Remarks if any.
Endpoint
http://{your-custom-domain-url}/api/shipment/{id}/addstatus
POST Request
http://{your-custom-domain-url}/api/shipment/{id}/addstatus
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success",
"shipments": "[...]"
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Account management

Overview As people join and leave your organization, you need to grant and revoke access to Waybill.work platform. This set of guides introduces the concepts of account management and deactivation through the use of the API. This set of API calls will allow you manage your customers and drivers who are stored on your user directory.
Account Management API
The Account Management API for Workplace is a REST API. This specification was designed to easily manage user identities in client apps and services.
Endpoints

Create Account

Signup API is a RESTful web service that allows you to trigger new signups from your app. Simply provide some basic user details (name, email, password etc.) and we'll send that user an activation email. Once the user clicks the activation link in the email they can start using the services.
Endpoint
/api/account/create
Post Params

Param Description
title 0 - 15 characters.
firstname 0 - 50 characters.
lastname 0 - 50 characters.
email Account email address.
phone Phone number (country code) (phone)
password Account password
password_confirmation Confirm password

Endpoint
http://{your-custom-domain-url}/api/account/create
POST Request
http://{your-custom-domain-url}/api/account/create
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Update Account

Update API is a RESTful web service that allows you to update user account from your app. By sending POST request to endpoint /api/account/update with profile details to update the current user account.
Endpoint
/api/account/update
Post Params

Param Description
title 0 - 15 characters.
firstname 0 - 50 characters.
lastname 0 - 50 characters.
email Account email address.
phone Phone number (country code) (phone)

Endpoint
http://{your-custom-domain-url}/api/account/update
POST Request
http://{your-custom-domain-url}/api/account/update
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Add address

Address API is a RESTful web service that allows you to add address to user address book from your app. By sending POST request to endpoint /api/account/address with address details to add address the current user account.
Endpoint
/api/account/address/all
/api/account/address/create
/api/account/address/{id}/update
/api/account/address/{id}/delete
Post Params

Param Description
name 0 - 15 characters
phone Phone number (country code) (phone)
street_address Address line 1 + Address line 2
city City name
state State name
country Country name
code Zipcode of the address

Endpoint
http://{your-custom-domain-url}/api/account/address/create
POST Request
http://{your-custom-domain-url}/api/account/address/create
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Reset Password

Note that setting a user password using via this API is comparable to using our in-browser, form-based Change Password functionality on top of an encrypted channel. Note also that when you set a password via this API, the password change must comply with your third-party user directory’s password policy for the user. However, password policy checks are enforced by default, which is consistent with the Change Password functionality in the web.

Endpoint
/api/account/password/change
Post Params
Param Description
old_password Account current password
new_password New password
confirm_password Confirm new password

Endpoint
http://{your-custom-domain-url}/api/account/password/change
POST Request
http://{your-custom-domain-url}/api/account/password/change
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Deactivate Account

Use this call to deactivate a user’s account based on the policy assigned to the user, for a specific time you define in the request, or until you re activate it.

Endpoint
/api/account/deactivate

Endpoint
http://{your-custom-domain-url}/api/account/deactivate
POST Request
http://{your-custom-domain-url}/api/account/deactivate
Headers
Authorization: Bearer {access_token}
Accept: application/json
Response
{
"status":"success"
"code":200
}
200 OK
400 Bad Request
401 Unauthorized
402 Request Failed
404 Not Found
409 Conflict
429 Too Many Requests
500, 502, 503, 504 Server Errors

Developer Support

Have a how-to question? Seeing a weird error? Ask us about it at developers@waybill.work.
Found a bug? Submit a support ticket.
Have a product idea or request? Share it with us at feedbacks@waybill.work.