Introduction

Welcome to the Vanlo API! You can use our API to verify addresses, rate and create shipments and shipping labels, and monitor tracking codes.

This is an EasyPost-compatible API, so switching from EasyPost to Vanlo is as simple as changing your request URL and API key!

We have client libraries / SDKs for Ruby, Python, PHP and C#. You can view code examples on the right, and you can switch the programming language of the examples with the tabs in the top right.

Request URL

Test: https://test.vanlo.com/api/v1/...

Production: https://www.vanlo.com/api/v1/...

Authentication

Authentication is performed by including your API key with every request (cURL), or by setting it globally in one of our client libraries / SDKs:

curl -X METHOD https://www.vanlo.com/api/v1/... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'

Vanlo.api_key = 'VANLO_API_KEY'

import vanlo

vanlo.api_key = 'VANLO_API_KEY'

require_once("/path/to/lib/vanlo.php");

\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

using Vanlo;

ClientManager.SetCurrent("VANLO_API_KEY");

Make sure to replace VANLO_API_KEY with your API key.

Vanlo uses API keys for authentication and identification.

Vanlo expects for the API key to be included in all API requests as an authorization bearer token:

Authorization: Bearer VANLO_API_KEY

Test Environment

In the client libraries / SDKs you can access the test environment by setting the API base value before performing any actions:

curl -X METHOD https://test.vanlo.com/api/v1/... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'

Vanlo.api_key = 'VANLO_API_KEY'
Vanlo.api_base = 'https://test.vanlo.com/api/v1'

import vanlo

vanlo.api_key = 'VANLO_API_KEY'
vanlo.api_base = 'https://test.vanlo.com/api/v1'

require_once("/path/to/lib/vanlo.php");

\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');
\Vanlo\Vanlo::setApiBase('https://test.vanlo.com/api/v1');

using Vanlo;

ClientManager.SetCurrent("VANLO_API_KEY", "https://test.vanlo.com/api/v1");

Vanlo offers a test environment which you can develop against without incurring any real charges or generating any live postage labels or tracking codes.

You can find your test API Key by logging in to the Vanlo Dashboard, entering "test mode" by clicking the toggle in the bottom of the left side bar, and then visiting the API Keys page: https://dashboard.vanlo.com/apikey

Shipments

Shipment Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "shp_"
object	string	"Shipment"
usps_zone	integer	The USPS zone of the shipment, if purchased with USPS
to_address	<Address>	The destination address
from_address	<Address>	The origin address
parcel	<Parcel>	The dimensions and weight of the package
customs_info	<CustomsInfo>	Information for the processing of customs
rates	[<Rate>...]	All associated Rate objects
selected_rate	<Rate>	The specific rate purchased for the shipment, or null if unpurchased or purchased through another mechanism
tracker	<Tracker>	The associated Tracker object
postage_label	<PostageLabel>	The associated PostageLabel object
refund_status	string	The current status of the shipment refund process. Possible values are "submitted", "refunded", "rejected"
tracking_code	string	If purchased, the tracking code will appear here as well as within the Tracker object
status	string	The current tracking status of the shipment
is_return	boolean	Set true to create as a return
options	<Options>	All of the options passed to the shipment, discussed in more depth below

Rate Object

Parameter	Type	Specification
id	string	Unique identifier, begins with 'rate_'
object	string	"Rate"
carrier	string	name of carrier
service	string	name of service
rate	string	the actual rate quote for this service
delivery_date	string	date for delivery
delivery_date_guaranteed	boolean	indicates if delivery window is guaranteed (true) or not (false)
delivery_days	string	delivery days for this service
created_at	datetime

PostageLabel Object

Parameter	Type	Specification
id	string	Unique identifier, begins with 'pl_'
object	string	"PostageLabel"
integrated_form	string
label_date	string	Date on label
label_epl2_url	string	URL for epl2 label(if applicable)
label_pdf_url	string	URL for PDF label(if applicable)
label_zpl_url	string	URL for ZPL label(if applicable)
label_resolution	string	Resolution of label image
label_size	string	size of label
label_type	string	Type of label
label_file_type	string	Label file type
label_url	string	URL of label image
created_at	datetime
updated_at	datetime

Options Object

Parameter	Type	Specification
label_date	string	Set the date that will appear on the postage label. Accepts ISO 8601 formatted string including time zone offset. Vanlo stores all dates as UTC time.
label_size	string	Size of label
label_format	string	Supported label formats include "PNG", "PDF", "ZPL", and "EPL2". "PNG" is the only format that allows for conversion
print_custom	[<PrintCustom>...]	You can optionally print custom messages on labels. The locations of these fields show up on different spots on the carrier's labels.
postage_label_inline	boolean
delivery_confirmation	string	If you want to request a signature, you can pass "ADULT_SIGNATURE" or "SIGNATURE". You may also request "NO_SIGNATURE" to leave the package at the door. "INDIRECT_SIGNATURE" is also an option for Fedex.
special_rates_eligibility	string	This option allows you to request restrictive rates from USPS. Can set to 'USPS.MEDIAMAIL' or 'USPS.LIBRARYMAIL'.

PrintCustom Object

Parameter	Type	Specification
value	string	Text to print on label
barcode	boolean	include value in barcode

Create a Shipment

curl -X POST https://www.vanlo.com/api/v1/shipments \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'shipment[to_address][name]=To Name' \
  -d 'shipment[to_address][street1]=To Street 1' \
  -d 'shipment[to_address][city]=To City' \
  -d 'shipment[to_address][state]=CA' \
  -d 'shipment[to_address][zip]=90277' \
  -d 'shipment[to_address][country]=US' \
  -d 'shipment[to_address][phone]=4151234567' \
  -d 'shipment[to_address][email]=to@example.com' \
  -d 'shipment[from_address][name]=From Name' \
  -d 'shipment[from_address][company]=From Company' \
  -d 'shipment[from_address][street1]=From Street 1' \
  -d 'shipment[from_address][street2]=From Street 2' \
  -d 'shipment[from_address][city]=From City' \
  -d 'shipment[from_address][state]=CA' \
  -d 'shipment[from_address][zip]=94104' \
  -d 'shipment[from_address][country]=US' \
  -d 'shipment[from_address][phone]=4157654321' \
  -d 'shipment[from_address][email]=from@example.com' \
  -d 'shipment[parcel][length]=8.1' \
  -d 'shipment[parcel][width]=7.2' \
  -d 'shipment[parcel][height]=6' \
  -d 'shipment[parcel][weight]=65.9'

# OR reference previously created objects

curl -X POST https://www.vanlo.com/api/v1/shipments \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'shipment[to_address][id]=adr_...' \
  -d 'shipment[from_address][id]=adr_...' \
  -d 'shipment[parcel][id]=prcl_...' \
  -d 'shipment[customs_info][id]=cstinfo_...'

require 'vanlo'
Vanlo.api_key = "VANLO_API_KEY"

Vanlo::Shipment.create(
  to_address: {
    name: 'To Name',
    street1: 'To Street',
    city: 'To City',
    state: 'CA',
    zip: '90277',
    country: 'US',
    phone: '4151234567',
    email: 'to@example.com'
  },
  from_address: {
    name: 'From Name',
    company: 'From Company',
    street1: 'From Street 1',
    street2: 'From Street 2',
    city: 'From City',
    state: 'CA',
    zip: '94104',
    country: 'US',
    phone: '4157654321',
    email: 'from@example.com'
  },
  parcel: {
    length: 8.1,
    width: 7.2,
    height: 6,
    weight: 65.9
  }
)

# OR reference previously created objects

to_address = Vanlo::Address.create(...)
from_address = Vanlo::Address.create(...)
parcel = Vanlo::Parcel.create(...)
customs_info = Vanlo::CustomsInfo.create(...)

Vanlo::Shipment.create(
  to_address: to_address,
  from_address: from_address,
  parcel: parcel,
  customs_info: customs_info
)

import vanlo
vanlo.api_key = "VANLO_API_KEY"

shipment = vanlo.Shipment.create(
  to_address={
    "name": 'To Name',
    "street1": 'To Street',
    "city": 'To City',
    "state": 'CA',
    "zip": '90277',
    "country": 'US',
    "phone": '4151234567',
    "email": 'to@example.com'
  },
  from_address={
    "name": 'From Name',
    "company": 'From Company',
    "street1": 'From Street 1',
    "street2": 'From Street 2',
    "city": 'From City',
    "state": 'CA',
    "zip": '94104',
    "country": 'US',
    "phone": '4157654321',
    "email": 'from@example.com'
  },
  parcel={
    "length": 8.1,
    "width": 7.2,
    "height": 6,
    "weight": 65.9
  }
)

# OR reference previously created objects

to_address = vanlo.Address.create(...)
from_address = vanlo.Address.create(...)
parcel = vanlo.Parcel.create(...)
customs_info = vanlo.CustomsInfo.create(...)

shipment = vanlo.Shipment.create(
  to_address=to_address,
  from_address=from_address,
  parcel=parcel,
  customs_info=customs_info
)

require_once("path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey("VANLO_API_KEY");

$shipment = \Vanlo\Shipment::create(array(
  "to_address" => array(
    'name' => 'To Name',
    'street1' => 'To Street',
    'city' => 'To City',
    'state' => 'CA',
    'zip' => '90277',
    'country' => 'US',
    'phone' => '4151234567',
    'email' => 'to@example.com'
  ),
  "from_address" => array(
    'name' => 'From Name',
    'company' => 'From Company',
    'street1' => 'From Street 1',
    'street2' => 'From Street 2',
    'city' => 'From City',
    'state' => 'CA',
    'zip' => '94104',
    'country' => 'US',
    'phone' => '4157654321',
    'email' => 'from@example.com'
  ),
  "parcel" => array(
    "length" => 8.1,
    "width" => 7.2,
    "height" => 6,
    "weight" => 65.9
  )
));

# OR reference previously created objects

$to_address = \Vanlo\Address::create(...);
$from_address = \Vanlo\Address::create(...);
$parcel = \Vanlo\Parcel::create(...);
$customs_info = \Vanlo\CustomsInfo::create(...);

$shipment = \Vanlo\Shipment::create(array(
  "to_address" => $to_address,
  "from_address" => $from_address,
  "parcel" => $parcel,
  "customs_info" => $customs_info
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Address fromAddress = new Address() {
    name = "From Name",
    company = "From Company",
    street1 = "From Street 1",
    street2 = "From Street 2",
    city = "From City",
    state = "CA",
    zip = "94104",
    country = "US",
    phone = "4157654321",
    email = "from@example.com"
 };

Address toAddress = new Address() {
    name = "To Name",
    street1 = "To Street",
    city = "To City",
    state = "CA",
    zip = "90277",
    country = "US",
    phone = "4151234567",
    email = "to@example.com"

};

Parcel parcel = new Parcel() {
    length = 8.1,
    width = 7.2,
    height = 6,
    weight = 65.9
};

Shipment shipment = new Shipment() {
    from_address = fromAddress,
    to_address = toAddress,
    parcel = parcel,
};

shipment.Create();

// OR reference previously created objects

Address to_address = Address.Create(...);
Address from_address = Address.Create(...);
Parcel parcel = Parcel.Create(...);
CustomsInfo customs_info = CustomsInfo.Create(...);

Shipment shipment = new Shipment() {
    to_address = to_address,
    from_address = from_address,
    parcel = parcel,
    customs_info = customs_info
};

shipment.Create();

The above command returns JSON structured like this:

{
  "id": "shp_...",
  "object": "Shipment",
    "to_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "To Name",
    "company": null,
    "street1": "To Street",
    "street2": null,
    "city": "To City",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4151234567",
    "residential": null,
    "email": "to@example.com",
    "created_at": "2019-04-22T05:39:56Z",
    "updated_at": "2019-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "From Name",
    "company": "From Company",
    "street1": "From Street 1",
    "street2": "From Street 2",
    "city": "From City",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4157654321",
    "email": "from@example.com",
    "residential": null,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_...",
    "object": "Parcel",
    "length": 8.2,
    "width": 7.1,
    "height": 6.0,
    "predefined_package": null,
    "weight": 65.9,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "rates": [
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "ParcelSelect",
      "rate": "9.02",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 5
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Express",
      "rate": "40.16",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Priority",
      "rate": "7.91",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2
    }
  ],
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": null,
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Shipments are the central objects of the Vanlo API. You will use them to send origin and destination addresses, parcel characteristics, and information for customs(when required).

Once a shipment is created we will attach the available shipping services (as Rate objects), and then a shipping label can be purchased by 'buying' one of the Rates.

An origin Address, destination Address, and Parcel are required for domestic rating and shipping. You will also have to include CustomsInfo whenever a shipment requires it (or include it on all shipments to simplify application logic).

The associated Rates, Tracker, and PostageLabel are generated by Vanlo and cannot be modified directly.

HTTP Request

POST https://www.vanlo.com/api/v1/shipments

Create Shipment Request Parameters

Parameter	Example
to_address	<Address>
from_address	<Address>
parcel	<Parcel>
customs_info	<CustomsInfo>

Buy a Shipment

curl -X POST https://www.vanlo.com/api/v1/shipments/shp_.../buy \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'rate[id]=rate_...'

require 'vanlo'
Vanlo.api_key = "VANLO_API_KEY"

shipment = Vanlo::Shipment.retrieve("shp_...")
shipment.buy(rate: shipment.lowest_rate)

import vanlo
vanlo.api_key = "VANLO_API_KEY"

shipment = vanlo.Shipment.retrieve("shp_...")
shipment.buy(rate=shipment.lowest_rate())

require_once("path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey("VANLO_API_KEY");

$shipment = \Vanlo\Shipment::retrieve("shp_...");
$shipment->buy(array(
  'rate'      => $shipment->lowest_rate()
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Shipment shipment = Shipment.Retrieve("shp...");
Rate lowestRate = shipment.LowestRate();

shipment.Buy(lowestRate);

The above command returns JSON structured like this:

{
  "id": "shp_...",
  "object": "Shipment",
  "to_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "To Name",
    "company": null,
    "street1": "To Street",
    "street2": null,
    "city": "To City",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4151234567",
    "residential": null,
    "email": "to@example.com",
    "created_at": "2019-04-22T05:39:56Z",
    "updated_at": "2019-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "From Name",
    "company": "From Company",
    "street1": "From Street 1",
    "street2": "From Street 2",
    "city": "From City",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4157654321",
    "email": "from@example.com",
    "residential": null,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_...",
    "object": "Parcel",
    "length": 8.2,
    "width": 7.1,
    "height": 6,
    "predefined_package": null,
    "weight": 65.9,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "rates": [
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "ParcelSelect",
      "rate": "9.02",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 5
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Express",
      "rate": "40.16",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Priority",
      "rate": "7.91",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2
    }
  ],
  "selected_rate": {
    "id": "rate_...",
    "object": "Rate",
    "created_at": "2019-04-22T05:40:57Z",
    "carrier": "USPS",
    "service": "Priority",
    "rate": "7.91",
    "delivery_date": null,
    "delivery_date_guaranteed": false,
    "delivery_days": 2
  },
  "postage_label": {
    "object": "PostageLabel",
    "created_at": "2019-04-22T05:40:57Z",
    "updated_at": "2019-04-22T05:40:57Z",
    "id": "pl_...",
    "integrated_form": null,
    "label_date": "2019-04-23",
    "label_epl2_url": null,
    "label_file_type": "image/png",
    "label_pdf_url": null,
    "label_resolution": null,
    "label_size": null,
    "label_type": null,
    "label_url": "https://....png",
    "label_zpl_url": null
  },
  "tracker": {
    "object": "Tracker",
    "created_at": "2019-04-22T05:40:57Z",
    "updated_at": "2019-04-22T05:40:57Z",
    "id": "trk_...",
    "shipment_id": "shp_...",
    "status": null,
    "tracking_code": "9405500205903028777744",
    "tracking_details": [],
    "public_url": null
  },
  "options": {
    "label_format": "png"
  },
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

To purchase a Shipment you only need to specify the Rate to purchase. This operation creates a Tracker and PostageLabel and returns the updated Shipment. The default image format of the associated PostageLabel is PNG. To change this default see the label_format option.

HTTP Request

POST https://www.vanlo.com/api/v1/shipments/:id/buy

Buy Shipment Request Parameters

Parameter	Example
rate	{id: "rate_..."}

Refund a Shipment

curl -X POST https://www.vanlo.com/api/v1/shipments/shp_.../refund \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = "VANLO_API_KEY"

shipment = Vanlo::Shipment.retrieve("shp_...")
shipment.refund

import vanlo
vanlo.api_key = "VANLO_API_KEY"

shipment = vanlo.Shipment.retrieve("shp_...")
shipment.refund()

require_once("path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey("VANLO_API_KEY");

$shipment = \Vanlo\Shipment::retrieve("shp_...");
$shipment->refund();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Shipment ship ment = Shipment.Retrieve("shp...");
shipment.Refund();

The above command returns JSON structured like this:

{
  "id": "shp_...",
  "object": "Shipment",
  "to_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "To Name",
    "company": null,
    "street1": "To Street",
    "street2": null,
    "city": "To City",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "4151234567",
    "residential": null,
    "email": "to@example.com",
    "created_at": "2019-04-22T05:39:56Z",
    "updated_at": "2019-04-22T05:39:56Z"
  },
  "from_address": {
    "id": "adr_...",
    "object": "Address",
    "name": "From Name",
    "company": "From Company",
    "street1": "From Street 1",
    "street2": "From Street 2",
    "city": "From City",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4157654321",
    "email": "from@example.com",
    "residential": null,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "parcel": {
    "id": "prcl_...",
    "object": "Parcel",
    "length": 8.2,
    "width": 7.1,
    "height": 6.0,
    "predefined_package": null,
    "weight": 65.9,
    "created_at": "2019-04-22T05:39:57Z",
    "updated_at": "2019-04-22T05:39:57Z"
  },
  "rates": [
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "ParcelSelect",
      "rate": "9.02",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 5
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Express",
      "rate": "40.16",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": null
    },
    {
      "id": "rate_...",
      "object": "Rate",
      "created_at": "2019-04-22T05:39:57Z",
      "carrier": "USPS",
      "service": "Priority",
      "rate": "7.91",
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "delivery_days": 2
    }
  ],
  "selected_rate": null,
  "postage_label": null,
  "tracking_code": null,
  "refund_status": "submitted",
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Once the refund has been submitted, refund_status attribute of the Shipment will be populated with one of the possible values: "submitted", "refunded", "rejected".

HTTP Request

POST https://www.vanlo.com/api/v1/shipments/:id/refund

Refund Shipment Request Parameters

Parameter	Example
id	shp_...

Addresses

Create an address

curl -X POST https://www.vanlo.com/api/v1/addresses \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d "address[company]=VANLO" \
  -d "address[street1]=123 MONTGOMERY ST" \
  -d "address[street2]=STE 400" \
  -d "address[city]=SAN FRANCISCO" \
  -d "address[state]=CA" \
  -d "address[zip]=94104" \
  -d "address[country]=US" \
  -d "address[phone]=4151234567"

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Address.create(
  company: "VANLO",
  street1: "123 MONTGOMERY ST",
  street2: "STE 400",
  city: "SAN FRANCISCO",
  state: "CA",
  zip: "94104",
  country: "US",
  phone: "4151234567"
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Address.create(
  company="VANLO",
  street1="123 MONTGOMERY ST",
  street2="STE 400",
  city="SAN FRANCISCO",
  state="CA",
  zip="94104",
  country="US",
  phone="4151234567"
)

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$address_params = array(
  "company" => "VANLO",
  "street1" => "123 MONTGOMERY ST",
  "street2" => "STE 400",
  "city" => "SAN FRANCISCO",
  "state" => "CA",
  "zip" => "94104",
  "country" => "US",
  "phone" => "4151234567"
);

\Vanlo\Address::create($address_params);

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Address address = Address.Create(
    new Dictionary<string, object>() {
        { "street1", "123 MONTGOMERY ST" },
        { "street2", "STE 400" },
        { "city", "SAN FRANCISCO" },
        { "state", "CA" },
        { "zip", "94104" },
        { "country", "US" },
        { "phone", "415-123-4567" }
    }
);

The above command returns JSON structured like this:

{
  "id": "adr_...",
  "object": "Address",
  "created_at": "2019-09-06T12:01:52.503Z",
  "updated_at": "2019-09-06T12:01:52.503Z",
  "name": null,
  "company": "VANLO",
  "street1": "123 MONTGOMERY ST",
  "street2": "STE 400",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "residential": false
}

This endpoint retrieves a specific address.

HTTP Request

POST https://www.vanlo.com/api/v1/addresses

Create Address Request Parameters

Parameter	Notes
name	Name associated with address
company	Company associated with address
street1	Address line 1
street2	Address line 2
city	City
state	State (2 digit in US, CA, AU)
zip	Zip or postal code
country	Country code (2-digit ISO 3166)
phone	Phone number
email	Email
residential	'true' or 'false'
verify	set to 'delivery' to verify

Get a Specific Address

curl -X GET https://www.vanlo.com/api/v1/addresses/adr_... \
  -H 'Authorization: Bearer VANLO_API_KEY' \

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Address.retrieve('adr_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Address.retrieve('adr_...')

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

\Vanlo\Address::retrieve('adr_...');

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Address address = Address.Retrieve("adr_...");

The above command returns JSON structured like this:

{
  "id": "adr_...",
  "object": "Address",
  "created_at": "2019-09-06T12:01:52.503Z",
  "updated_at": "2019-09-06T12:01:52.503Z",
  "name": null,
  "company": "VANLO",
  "street1": "123 MONTGOMERY ST",
  "street2": "STE 400",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94104",
  "country": "US",
  "phone": "4151234567",
  "email": null,
  "residential": false
}

This endpoint retrieves a specific address.

HTTP Request

GET https://www.vanlo.com/api/v1/addresses/:id

Parcels

Create a Parcel

curl -X POST https://api.vanlo.com/api/v1/parcels \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'parcel[length]=20.2' \
  -d 'parcel[width]=10.9' \
  -d 'parcel[height]=5' \
  -d 'parcel[weight]=65.9'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Parcel.create(
  length: 20.2,
  width: 10.9,
  height: 5,
  weight: 65.9
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Parcel.create(
  length=20.2,
  width=10.9,
  height=5,
  weight=65.9
)

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

\Vanlo\Parcel::create(array(
    "length" => 20.2,
    "width" => 10.9,
    "height" => 5,
    "weight" => 65.9
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Parcel parcel = Parcel.Create(new Dictionary<string, object>() {
    { "length", 10 },
    { "width", 20 },
    { "height", 5 },
    { "weight", 1.8 }
});

The above command returns JSON structured like this:

{
  "id": "prcl_...",
  "object": "Parcel",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Create commonly sized parcels and save the returned id for use in future shipments. Remember to use the correct predefined_package when shipping with carrier supplied packaging.

HTTP Request

POST https://www.vanlo.com/api/v1/parcels

Create Parcel Request Parameters

Parameter	Notes
length	20.2
width	10.9
height	5
weight	65.9
predefined_package	List of Predefined Packages

Retrieve a Parcel

curl -X GET https://www.vanlo.com/api/v1/parcels/prcl_... \
  -H 'Authorization: Bearer VANLO_API_KEY' \

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Parcel.retrieve("prcl_...")

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Parcel.retrieve("prcl_...")

require_once("/path/to/lib/vanlo.php");
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

\Vanlo\Parcel::retrieve("prcl_...");

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Parcel parcel = Parcel.Retrieve("prcl_...");

The above command returns JSON structured like this:

{
  "id": "prcl_...",
  "object": "Parcel",
  "length": 20.2,
  "width": 10.9,
  "height": 5.0,
  "predefined_package": null,
  "weight": 65.9,
  "created_at": "2019-04-22T05:40:57Z",
  "updated_at": "2019-04-22T05:40:57Z"
}

Get a Parcel by its id. In general you should not need to use this in your automated solution. A Parcel's id can be inlined into the creation call to other objects. This allows you to only create one Parcel for each package you will be using.

HTTP Request

GET https://vanlo.com/api/v1/parcels/:id

CustomsInfos

Create CustomsInfo

curl -X POST https://www.vanlo.com/api/v1/customs_infos \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'customs_info[customs_certify]=true' \
  -d 'customs_info[customs_signer]=Name of Signer' \
  -d 'customs_info[contents_type]=merchandise' \
  -d 'customs_info[contents_explanation]=' \
  -d 'customs_info[restriction_type]=none' \
  -d 'customs_info[eel_pfc]=NOEEI 30.37(a)' \
  -d 'customs_info[customs_items][0][description]=Button' \
  -d 'customs_info[customs_items][0][quantity]=2' \
  -d 'customs_info[customs_items][0][value]=23' \
  -d 'customs_info[customs_items][0][weight]=11' \
  -d 'customs_info[customs_items][0][hs_tariff_number]=112233'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::CustomsInfo.create(
  customs_certify: true,
  customs_signer: 'Name of Signer',
  contents_type: 'merchandise',
  restriction_type: 'none',
  eel_pfc: 'NOEEI 30.37(a)',
  customs_items: [
    {
      description: 'Button',
      quantity: '2',
      value: '23',
      weight: '11',
      hs_tariff_number:'11223',
    }
  ]
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

customs_info = vanlo.CustomsInfo.create(
    customs_certify=True,
    customs_signer='Name of Signer',
    contents_type='merchandise',
    restriction_type='none',
    eel_pfc='NOEEI 30.37(a)',
    customs_items=[{
        'description': 'Button',
        'quantity': '2',
        'value': '23',
        'weight': '11',
        'hs_tariff_number':'11223',
    }]
)

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$customs_info = \Vanlo\CustomsInfo::create(array(
  'customs_certify' => true,
  'customs_signer' => 'Name of Signer',
  'contents_type' => 'merchandise',
  'restriction_type' => 'none',
  'eel_pfc' => 'NOEEI 30.37(a)',
  'customs_items' => array(array(
    'description' => 'Button',
    'quantity' => 2,
    'value' => 23,
    'weight' => 11,
    'hs_tariff_number' => '11223',
  ))
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Dictionary<string, object> item = new Dictionary<string, object>() {
    { "description", "TShirt" },
    { "quantity", 1 },
    { "weight", 8 },
    { "origin_country", "US" }
};

CustomsInfo info = CustomsInfo.Create(new Dictionary<string, object>() {
    { "customs_certify", true },
    { "eel_pfc", "NOEEI 30.37(a)" },
    { "customs_signer", "Steve Brule" },
    { "contents_type", "merchandise" },
    { "customs_items", new List<Dictionary<string, object>>() { item } }
});

The above command returns JSON structured like this:

{
  "id": "cstinfo_...",
  "object": "CustomsInfo",
  "contents_explanation": null,
  "contents_type": "merchandise",
  "customs_certify": true,
  "customs_signer": "Name of Signer",
  "eel_pfc": "NOEEI 30.37(a)",
  "non_delivery_option": "return",
  "restriction_comments": null,
  "restriction_type": "none",
  "customs_items": [{
      "id": "cstitem_...",
      "object": "CustomsItem",
      "description": "T-Shirt",
      "hs_tariff_number": "123456",
      "origin_country": "US",
      "quantity": 1,
      "value": 10,
      "weight": 5,
      "created_at": "2019-04-22T07:17:51Z",
      "updated_at": "2019-04-22T07:17:51Z"
    }, {
      "id": "cstitem_...",
      "object": "CustomsItem",
      "description": "Button",
      "hs_tariff_number": "112233",
      "origin_country": "US",
      "quantity": 2,
      "value": 23,
      "weight": 11,
      "created_at": "2019-04-22T07:17:51Z",
      "updated_at": "2019-04-22T07:17:51Z"
    }
  ],
  "created_at": "2019-04-22T07:17:51Z",
  "updated_at": "2019-04-22T07:17:51Z"
}

A CustomsItem object describes goods for international shipment and should be created then included in a CustomsInfo object.

HTTP Request

POST https://www.vanlo.com/api/v1/customs_infos

Create CustomsInfo Request Parameters

Parameter	Notes
eel_pfc	for values less than $2500 use 'NOEEI 30.37(a)'
contents_type	'documents', 'gift', 'merchandise', 'returned_goods', 'sample', or 'other'
contents_explanation	description of goods when contents_type is 'other'
customs_certify	'true' or 'false'
customs_signer	Name of individual certifying info
restriction_type	'none', 'other', 'quarantine', or 'sanitary_phytosanitary_inspection'
restriction_comments	required when restriction_type is 'other'
non_delivery_option	'abandon' or 'return' (default)
customs_items	[<CustomsItem>,<CustomsItem>,...]

Batches

Create a Batch

curl -X POST https://www.vanlo.com/api/v1/batches \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'batch[shipments][0][id]=shp_...' \
  -d 'batch[shipments][1][id]=shp_...'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Batch.create(shipments: [shipment])

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Batch.create(shipments = [shipment]);

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::create(array(
  'shipments' => array(array(
    'id' => 'shp_...'
  ))
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Create(new Dictionary<string, object>() {
    { "shipments", new List<Dictionary<string, object>>() {
        new Dictionary<string, object>() { { "id", "shp_..." } }
    } }
});

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "object": "Batch",
  "num_shipments": 2,
  "reference": null,
  "scan_form": null,
  "shipments": [
    ....
  ],
  "state": "creating",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 2,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

A Batch can be created with or without Shipments. When created with Shipments the initial state will be 'creating'. Once the state changes to created a webhook Event will be sent. When created with no Shipments the initial state will be 'created' and a webhook will be sent.

HTTP Request

POST https://www.vanlo.com/api/v1/batches

Create Batch Parameters

Parameter	Example
shipments	[<Shipment>,<Shipment>,...]

Batch Labels

curl -X POST https://www.vanlo.com/api/v1/batches/batch_.../label \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'file_format=zpl'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

batch = Vanlo::Batch.retrieve('batch_...')
batch.label(file_format: 'zpl')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

batch = vanlo.Batch.retrieve('batch_...')
batch.label(file_format = 'zpl')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::retrieve('batch_...');
$batch->label(array('file_format' => 'zpl'));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Retrieve("batch_...");

batch.GenerateLabel("zpl");

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "num_shipments": 2,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    ....
  ],
  "state": "creating",
  "status": {
    "created": 0,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 2,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

One of the advantages of processing Shipments in batches is the ability to consolidate the PostageLabel into one file. This can only be done once for each batch and all Shipments must have a status of 'postage_purchased'.

Available label formats are 'pdf', 'zpl' or 'epl2' format.

HTTP Request

POST https://www.vanlo.com/api/v1/batches/:id/label

Batch Label Parameters

Parameter	Notes
file_format	'pdf', 'zpl', or 'epl2'

Scan Forms

curl -X POST https://www.vanlo.com/api/v1/batches/batch_.../scan_form \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

batch = Vanlo::Batch.retrieve('batch_...')
batch.create_scan_form

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

batch = vanlo.Batch.retrieve('batch_...')
batch.create_scan_form()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::retrieve('batch_...');
$batch->create_scan_form();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Retrieve("batch_...");

batch.GenerateScanForm();

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "num_shipments": 2,
  "object": "Batch",
  "reference": null,
  "scan_form": null,
  "shipments": [
    ....
  ],
  "state": "creating",
  "status": {
    "created": 2,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 0,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

See Scan Form rules and Object Definition.

HTTP Request

POST https://www.vanlo.com/api/v1/batches/:id/scan_form

Get a specific Batch

curl -X GET https://www.vanlo.com/api/v1/batches/batch_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Batch.retrieve('batch_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Batch.retrieve('batch_...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$batch = \Vanlo\Batch::retrieve('batch_...');

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Batch batch = Batch.Retrieve("batch_...");

The above command returns JSON structured like this:

{
  "id": "batch_...",
  "object": "Batch",
  "num_shipments": 2,
  "reference": null,
  "scan_form": null,
  "shipments": [
    ....
  ],
  "state": "creating",
  "status": {
    "created": 2,
    "queued_for_purchase": 0,
    "creation_failed": 0,
    "postage_purchased": 0,
    "postage_purchase_failed": 0
  },
  "label_url": null,
  "created_at": "2019-07-22T07:34:39Z",
  "updated_at": "2019-07-22T07:34:39Z"
}

This endpoint retrieves a specific batch.

HTTP Request

GET https://www.vanlo.com/api/v1/batches/:id

ScanForms

Create a ScanForm

curl -X POST https://www.vanlo.com/api/v1/scan_forms \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'shipments[0][id]=shp_...' \
  -d 'shipments[1][id]=shp_...'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

shipment = Vanlo::Shipment.retrieve('shp_...')

Vanlo::ScanForm.create(shipments: [shipment])

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.ScanForm.create(shipments=[shipment])

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$shipment = \Vanlo\Shipment::retrieve('shp_...')

$scan_form = \Vanlo\ScanForm::create(array(
  'shipments' => array($shipment)
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

List<Shipment> shipments = new List<Shipment>() {
    new Shipment() { id = "shp_..." }
};

ScanForm scanForm = ScanForm.Create(shipments);

The above command returns JSON structured like this:

{
   "id":"sf_...",
   "object":"ScanForm",
   "created_at":"2019-01-20T22:59:03Z",
   "updated_at":"2019-01-20T22:59:04Z",
   "tracking_codes":[
      "8888888888888888888888"
   ],
   "address":{
      "id":"adr_...",
      "object":"Address",
      "created_at":"2019-10-04T19:08:20Z",
      "updated_at":"2019-10-04T19:08:20Z",
      "name":"Vanlo",
      "company":null,
      "street1":"123 MONTGOMERY ST",
      "street2":"STE 400",
      "city":"SAN FRANCISCO",
      "state":"CA",
      "zip":"94104",
      "country":"US",
      "phone":"4151234567",
      "email":"from@example.com",
      "residential":null,
      "verifications":{}
   },
   "status":"created",
   "message":null,
   "form_url":"https://....pdf",
   "form_file_type":null,
   "batch_id":"batch_...",
   "confirmation":null
}

A ScanForm can be created in two ways:

Add Shipments to a Batch and create a ScanForm for a Batch of Shipments or create a ScanForm for shipments directly without adding shipments to a Batch.

Note: A Batch is created in the background for Shipments as an intermediate process to creating ScanForms. You can create a ScanForm for 1 or a group of Shipments.

HTTP Request

POST https://www.vanlo.com/api/v1/scan_forms

Create ScanForm Request Parameters

Parameter	Example
shipments	[<Shipment>,<Shipment>,...]

Retrieve a list of a ScanForms

curl -X GET https://www.vanlo.com/api/v1/scan_forms \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'page_size=2'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::ScanForm.all(page_size: 2)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.ScanForm.all(page_size=2)

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$scan_forms = \Vanlo\ScanForm::all(array('page_size' => 2));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

var listParams = new Dictionary<string, object>() {
    { "page_size", 2 },
    { "start_datetime", "2016-01-02T08:50:00Z" }
};

ScanFormList scanFormList = ScanForm.List(listParams);

The above command returns JSON structured like this:

{
  "scan_forms":[
    {
      "id":"sf_...",
      "object":"ScanForm",
      "created_at":"2019-01-20T23:06:56Z",
      "updated_at":"2019-01-20T23:06:56Z",
      "tracking_codes":[
        "8888888888888888888888"
      ],
      "address":{
        "id":"adr_...",
        "object":"Address",
        "created_at":"2019-10-04T19:08:20Z",
        "updated_at":"2019-10-04T19:08:20Z",
        "name":"Vanlo",
        "company":null,
        "street1":"123 MONTGOMERY ST",
        "street2":"STE 400",
        "city":"SAN FRANCISCO",
        "state":"CA",
        "zip":"94104",
        "country":"US",
        "phone":"4151234567",
        "email":"from@example.com",
        "residential":null,
        "verifications":{}
      },
      "status":"created",
      "message":null,
      "form_url":"https://vanlo-files.s3-us-west-2.amazonaws.com/files/scan_form/20170120/f02edb1487474db2b7dddd36d467e1f1.pdf",
      "batch_id":"batch_...",
    },
    {
      "id":"sf_...",
      "object":"ScanForm",
      "created_at":"2019-01-20T23:06:48Z",
      "updated_at":"2019-01-20T23:06:48Z",
      "tracking_codes":[],
      "address":null,
      "status":"failed",
      "message":"A consistent from_address is required to create a USPS ScanForm.",
      "form_url":null,
      "batch_id":"batch_...",
    }
  ],
  "has_more":true
}

The ScanForm List is a paginated list of all ScanForm objects associated with the given API key. It accepts a variety of parameters which can be used to modify the scope. The 'has_more' attribute indicates whether or not additional pages can be requested. The recommended way of paginating is to use either the 'before_id' or 'after_id' parameter to specify where the next page begins.

HTTP Request

GET https://www.vanlo.com/api/v1/scan_forms

Retrieve a list of ScanForms Request Parameters

Parameter	Example
before_id	sf_...
after_id	sf_...
start_datetime	2019-01-02T00:00:00Z
end_datetime	2019-01-02T00:00:00Z
page_size	20

Retrieve a ScanForm

curl -X GET https://www.vanlo.com/api/v1/scan_forms/sf_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::ScanForm.retrieve('sf_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.ScanForm.retrieve('sf_...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$scan_form = \Vanlo\ScanForm::retrieve('sf_...')

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

ScanForm otherScanForm = ScanForm.Retrieve("sf_...");

The above command returns JSON structured like this:

{
   "id":"sf_...",
   "object":"ScanForm",
   "created_at":"2019-01-20T22:59:03Z",
   "updated_at":"2019-01-20T22:59:04Z",
   "tracking_codes":[
      "8888888888888888888888"
   ],
   "address":{
      "id":"adr_...",
      "object":"Address",
      "created_at":"2019-10-04T19:08:20Z",
      "updated_at":"2019-10-04T19:08:20Z",
      "name":"Vanlo",
      "company":null,
      "street1":"123 MONTGOMERY ST",
      "street2":"STE 400",
      "city":"SAN FRANCISCO",
      "state":"CA",
      "zip":"94104",
      "country":"US",
      "phone":"4151234567",
      "email":"from@example.com",
      "residential":null,
      "verifications":{}
   },
   "status":"created",
   "message":null,
   "form_url":"https://....pdf",
   "batch_id":"batch_...",
}

Retrieve a ScanForm by id.

HTTP Request

GET https://www.vanlo.com/api/v1/scan_forms/:id

Retrieve a ScanForm Request Parameters

Parameter	Example
id	sf_...

Trackers

Tracker Object

Parameter	Type	Specification
id	string	Unique identifier, begins with "trk_"
object	string	"Tracker"
shipment_id	string	The id of the Shipment object associated with the Tracker (if any)
tracking_details	[<TrackingDetails>...]	Array of the associated TrackingDetail objects
carrier_detail	[<CarrierDetail>...]	associated CarrierDetail object
carrier	string	The name of the carrier handling the shipment
status	string	The current status of the package, possible values are "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"
tracking_code	string	The tracking code provided by the carrier
public_url	string	URL to a publicly-accessible html page that shows tracking details for this tracker
created_at	datetime
updated_at	datetime

CarrierDetail Object

Parameter	Type	Specification
object	string	"CarrierDetail"
service	string	The service level the associated shipment was shipped with (if available)
container_type	string	The type of container the associated shipment was shipped in (if available)
origin_location	string	The location from which the package originated, stringified for presentation (if available)
alternate_identifier	string	The alternate identifier for this package as provided by the carrier (if available)
destination_location	string	The location to which the package is being sent, stringified for presentation (if available)
est_delivery_date_local	string	The estimated delivery date as provided by the carrier, in the local time zone (if available)
est_delivery_time_local	string	The estimated delivery time as provided by the carrier, in the local time zone (if available)
guaranteed_delivery_date	string	The date and time the carrier guarantees the package to be delivered by (if available)
initial_delivery_attempt	string	The date and time of the first attempt by the carrier to deliver the package (if available)
origin_tracking_location	<TrackingLocation>	The location from which the package originated
destination_tracking_location	<TrackingLocation>	The location to which the package is being sent

TrackingDetails Object

Parameter	Type	Specification
object	string	"TrackingDetail"
status	string	status of the package at the time of the scan event, possible values are "unknown", "pre_transit", "in_transit", "out_for_delivery", "delivered", "available_for_pickup", "return_to_sender", "failure", "cancelled" or "error"
message	string	Description of the scan event
source	string	The original source of the information for this scan event, usually the carrier
datetime	datetime	The timestamp when the tracking scan occurred
tracking_location	<TrackingLocation>	The location associated with the scan event
created_at	datetime
updated_at	datetime

TrackingLocation Object

Parameter	Type	Specification
zip	string	The postal code where the scan event occurred (if available)
city	string	The city where the scan event occurred (if available)
state	string	The state where the scan event occurred (if available)
country	string	The country where the scan event occurred (if available)

Testing Specific Tracking States

Sometimes you may want to simulate specific tracking statuses (e.g. "out_for_delivery") within your application to test how your application responds. Vanlo has a set of test tracking_codes that, when sent to the API, respond with specific tracking statuses and send a webhook Event to your test mode URL. The tracking updates that are sent by these tracking_codes will contain canned information, but it will be similar in form to the information normally provided by the carrier you selected.

Test Tracking Codes

tracking_code	status
EZ1000000001	pre_transit
EZ2000000002	in_transit
EZ3000000003	out_for_delivery
EZ4000000004	delivered
EZ5000000005	return_to_sender
EZ6000000006	failure
EZ7000000007	unknown

Create a Tracker

curl -X POST https://api.vanlo.com/api/v1/trackers \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'tracker[tracking_code]=EZ2000000002'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Tracker.create(
  tracking_code: 'EZ2000000002'
)

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Tracker.create(tracking_code='EZ2000000002')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');


$tracker = \Vanlo\Tracker::create(array(
  'tracking_code' => 'EZ2000000002',
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Tracker tracker = Tracker.Create("USPS", "EZ2000000002");

The above command returns JSON structured like this:

{
    "id": "trk_...",
    "object": "Tracker",
    "shipment_id": null,
    "tracking_details": [
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.467Z",
            "updated_at": "2020-03-31T16:09:53.467Z",
            "status": "pre_transit",
            "message": "Pre-Shipment information received",
            "datetime": "2020-02-29T16:09:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.487Z",
            "updated_at": "2020-03-31T16:09:53.487Z",
            "status": "pre_transit",
            "message": "Shipping label created",
            "datetime": "2020-03-01T10:58:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.500Z",
            "updated_at": "2020-03-31T16:09:53.500Z",
            "status": "in_transit",
            "message": "Picked Up",
            "datetime": "2020-03-01T16:09:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "94612",
                "city": "Oakland",
                "state": "CA",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.516Z",
            "updated_at": "2020-03-31T16:09:53.516Z",
            "status": "in_transit",
            "message": "Arrived at Sort Facility",
            "datetime": "2020-03-02T10:36:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.530Z",
            "updated_at": "2020-03-31T16:09:53.530Z",
            "status": "in_transit",
            "message": "Departed Sort Facility",
            "datetime": "2020-03-03T11:16:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T16:09:53.544Z",
            "updated_at": "2020-03-31T16:09:53.544Z",
            "status": "in_transit",
            "message": "Arrived at Distribution Center",
            "datetime": "2020-03-03T16:09:53.000Z",
            "source": null,
            "tracking_location": {
                "zip": "19087",
                "city": "Radnor",
                "state": "PA",
                "country": "US"
            }
        }
    ],
    "created_at": "2020-03-31T16:09:53.436Z",
    "updated_at": "2020-03-31T16:09:53.436Z",
    "carrier": "USPS",
    "status": "in_transit",
    "tracking_code": "EZ...",
    "public_url": "https://..."
}

A Tracker encapsulates all tracking information for a shipment.

HTTP Request

POST https://www.vanlo.com/api/v1/trackers

Create Tracker Parameters

Parameter	Example
tracking_code	EZ3000000003
carrier	USPS

List trackers

curl -X GET https://api.vanlo.com/api/v1/trackers \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Tracker.all

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Tracker.all(page_size = 2)

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$trackers = \Vanlo\Tracker::all(array(
  'page_size' => 2
));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

listParams = new Dictionary<string, object>() {
    { "page_size", 2 },
    { "start_datetime", "2016-01-02T08:50:00Z" }
};

TrackerList trackerList = Tracker.List(listParams);
TrackerList nextTrackerList = trackerList.Next();

The above command returns JSON structured like this:

{
    "trackers": [
        {
            "id": "trk_...",
            "object": "Tracker",
            "shipment_id": null,
            "tracking_details": [
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.580Z",
                    "updated_at": "2020-03-30T23:07:05.580Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment information received",
                    "datetime": "2020-02-29T23:07:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.599Z",
                    "updated_at": "2020-03-30T23:07:05.599Z",
                    "status": "pre_transit",
                    "message": "Shipping label created",
                    "datetime": "2020-03-01T17:56:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.622Z",
                    "updated_at": "2020-03-30T23:07:05.622Z",
                    "status": "in_transit",
                    "message": "Picked Up",
                    "datetime": "2020-03-01T23:07:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "94612",
                        "city": "Oakland",
                        "state": "CA",
                        "country": "US"
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.644Z",
                    "updated_at": "2020-03-30T23:07:05.644Z",
                    "status": "in_transit",
                    "message": "Arrived at Sort Facility",
                    "datetime": "2020-03-02T17:34:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "60290",
                        "city": "Chicago",
                        "state": "IL",
                        "country": "US"
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:07:05.666Z",
                    "updated_at": "2020-03-30T23:07:05.666Z",
                    "status": "in_transit",
                    "message": "Departed Sort Facility",
                    "datetime": "2020-03-03T18:14:05.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "60290",
                        "city": "Chicago",
                        "state": "IL",
                        "country": "US"
                    }
                }
            ],
            "created_at": "2020-03-30T23:07:05.547Z",
            "updated_at": "2020-03-30T23:07:05.547Z",
            "carrier": "USPS",
            "status": "out_for_delivery",
            "tracking_code": "EZ3000000003",
            "public_url": "https://..."
        },
        {
            "id": "trk_...",
            "object": "Tracker",
            "shipment_id": "shp_dab9ace301d690b3473d5e7f5c9dfba2",
            "tracking_details": [
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:08:45.296Z",
                    "updated_at": "2020-03-30T23:08:45.296Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment Info Sent to USPS",
                    "datetime": "2020-02-29T23:07:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:08:45.311Z",
                    "updated_at": "2020-03-30T23:08:45.311Z",
                    "status": "pre_transit",
                    "message": "Shipping Label Created",
                    "datetime": "2020-03-01T11:44:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77063",
                        "city": "HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.402Z",
                    "updated_at": "2020-03-30T23:09:45.402Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment Info Sent to USPS",
                    "datetime": "2020-02-29T23:08:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.416Z",
                    "updated_at": "2020-03-30T23:09:45.416Z",
                    "status": "pre_transit",
                    "message": "Shipping Label Created",
                    "datetime": "2020-03-01T11:45:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77063",
                        "city": "HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.430Z",
                    "updated_at": "2020-03-30T23:09:45.430Z",
                    "status": "in_transit",
                    "message": "Arrived at USPS Origin Facility",
                    "datetime": "2020-03-01T21:50:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77315",
                        "city": "NORTH HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.444Z",
                    "updated_at": "2020-03-30T23:09:45.444Z",
                    "status": "in_transit",
                    "message": "Arrived at USPS Facility",
                    "datetime": "2020-03-02T23:26:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "29201",
                        "city": "COLUMBIA",
                        "state": "SC",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.470Z",
                    "updated_at": "2020-03-30T23:09:45.470Z",
                    "status": "in_transit",
                    "message": "Arrived at Post Office",
                    "datetime": "2020-03-03T02:17:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "29407",
                        "city": "CHARLESTON",
                        "state": "SC",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:09:45.483Z",
                    "updated_at": "2020-03-30T23:09:45.483Z",
                    "status": "in_transit",
                    "message": "Sorting Complete",
                    "datetime": "2020-03-03T07:57:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "29407",
                        "city": "CHARLESTON",
                        "state": "SC",
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:10:45.659Z",
                    "updated_at": "2020-03-30T23:10:45.659Z",
                    "status": "pre_transit",
                    "message": "Pre-Shipment Info Sent to USPS",
                    "datetime": "2020-02-29T23:09:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": null,
                        "city": null,
                        "state": null,
                        "country": null
                    }
                },
                {
                    "id": null,
                    "object": "TrackingDetail",
                    "created_at": "2020-03-30T23:10:45.680Z",
                    "updated_at": "2020-03-30T23:10:45.680Z",
                    "status": "pre_transit",
                    "message": "Shipping Label Created",
                    "datetime": "2020-03-01T11:46:10.000Z",
                    "source": null,
                    "tracking_location": {
                        "zip": "77063",
                        "city": "HOUSTON",
                        "state": "TX",
                        "country": null
                    }
                }
            ],
            "created_at": "2020-03-30T23:07:09.998Z",
            "updated_at": "2020-03-30T23:07:09.998Z",
            "carrier": "USPS",
            "status": "unknown",
            "tracking_code": "9405....",
            "public_url": "https://..."
        }
    ],
    "has_more": true
}

Retrieve an paginated list of all Trackers available to the authenticated account.

HTTP Request

GET https://www.vanlo.com/api/v1/trackers

Get a Tracker

curl -X GET https://www.vanlo.com/api/v1/trackers/trk_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Tracker.retrieve('trk_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Tracker.retrieve('trk_...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$tracker = \Vanlo\Tracker::retrieve('trk_...');

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Tracker tracker = Tracker.Retrieve("trk_...");

The above command returns JSON structured like this:

{
    "id": "trk_...",
    "object": "Tracker",
    "shipment_id": null,
    "tracking_details": [
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.488Z",
            "updated_at": "2020-03-31T15:11:17.488Z",
            "status": "pre_transit",
            "message": "Pre-Shipment information received",
            "datetime": "2020-02-29T15:11:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.499Z",
            "updated_at": "2020-03-31T15:11:17.499Z",
            "status": "pre_transit",
            "message": "Shipping label created",
            "datetime": "2020-03-01T10:00:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": null,
                "city": null,
                "state": null,
                "country": null
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.510Z",
            "updated_at": "2020-03-31T15:11:17.510Z",
            "status": "in_transit",
            "message": "Picked Up",
            "datetime": "2020-03-01T15:11:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "94612",
                "city": "Oakland",
                "state": "CA",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.521Z",
            "updated_at": "2020-03-31T15:11:17.521Z",
            "status": "in_transit",
            "message": "Arrived at Sort Facility",
            "datetime": "2020-03-02T09:38:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.532Z",
            "updated_at": "2020-03-31T15:11:17.532Z",
            "status": "in_transit",
            "message": "Departed Sort Facility",
            "datetime": "2020-03-03T10:18:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "60290",
                "city": "Chicago",
                "state": "IL",
                "country": "US"
            }
        },
        {
            "id": null,
            "object": "TrackingDetail",
            "created_at": "2020-03-31T15:11:17.542Z",
            "updated_at": "2020-03-31T15:11:17.542Z",
            "status": "in_transit",
            "message": "Arrived at Distribution Center",
            "datetime": "2020-03-03T15:11:17.000Z",
            "source": null,
            "tracking_location": {
                "zip": "19087",
                "city": "Radnor",
                "state": "PA",
                "country": "US"
            }
        }
    ],
    "created_at": "2020-03-31T15:11:17.461Z",
    "updated_at": "2020-03-31T15:11:17.461Z",
    "carrier": "USPS",
    "status": "in_transit",
    "tracking_code": "EZ2...",
    "public_url": "https://..."
}

This endpoint retrieves a tracker.

HTTP Request

GET https://www.vanlo.com/api/v1/trackers/:id

Webhooks

Create a Webhook

curl -X POST https://www.vanlo.com/api/v1/webhooks \
  -H 'Authorization: Bearer VANLO_API_KEY' \
  -d 'webhook[url]=https://example.com'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Webhook.create(url: 'https://example.com')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Webhook.create(url='https://example.com')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook = \Vanlo\Webhook::create(array('url' => 'https://example.com'));

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Create(
    new Dictionary<string, object>() {
        { "url", "example.com" }
    }
);

The above command returns JSON structured like this:

{
   "id":"hook_...",
   "object":"Webhook",
   "url":"http://example.com",
   "disabled_at":null
}

To create a Webhook, you simply need to provide a url parameter that you wish to receive notifications to.

HTTP Request

POST https://www.vanlo.com/api/v1/webhooks

Create Webhook Request Parameters

Parameter	Example
url	example.com

Retrieve a list of Webhooks

curl -X GET https://www.vanlo.com/api/v1/webhooks \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Webhook.all

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

webhooks = vanlo.Webhook.all()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhooks = \Vanlo\Webhook::all();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

List<Webhook> webhooks = Webhook.List();

Retrieve an unpaginated list of all Webhooks available to the authenticated account.

The above command returns JSON structured like this:

{
   "webhooks":[
      {
         "id":"hook_...",
         "object":"Webhook",
         "url":"https://webhooks.example.com",
         "disabled_at":null
      },
      {
         "id":"hook_...",
         "object":"Webhook",
         "url":"http://example.com",
         "disabled_at":null
      }
   ]
}

HTTP Request

GET https://www.vanlo.com/api/v1/webhooks

Retrieve a Webhook

curl -X GET https://www.vanlo.com/api/v1/webhooks/hook_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

Vanlo::Webhook.retrieve('hook_...')

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

vanlo.Webhook.retrieve('hook...')

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook = \Vanlo\Webhook::retrieve("hook_...");

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Retrieve("hook_...");

The above command returns JSON structured like this:

{
   "id":"hook_...",
   "object":"Webhook",
   "url":"http://example.com",
   "disabled_at":null
}

Retrieve a Webhook by id.

HTTP Request

GET https://www.vanlo.com/api/v1/webhooks/:id

Retrieve Webhook Request Parameters

Parameter	Example
id	hook_...

Update a Webhook

curl -X PUT https://www.vanlo.com/api/v1/webhooks/hook_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

webhook = Vanlo::Webhook.retrieve('hook_...')
webhook.update

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

webhook = vanlo.Webhook.retrieve('hook_...')
webhook.update()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook = \Vanlo\Webhook::retrieve("hook_...");
$webhook->update();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Retrieve("hook_...");
webhook.Update();

The above command returns JSON structured like this:

{
   "id":"hook_...",
   "object":"Webhook",
   "url":"http://example.com",
   "disabled_at":null
}

Enables a Webhook that has been disabled.

HTTP Request

PUT https://www.vanlo.com/api/v1/webhooks/:id

Delete a Webhook

curl -X DELETE https://www.vanlo.com/api/v1/webhooks/hook_... \
  -H 'Authorization: Bearer VANLO_API_KEY'

require 'vanlo'
Vanlo.api_key = 'VANLO_API_KEY'

webhook = Vanlo::Webhook.retrieve('hook_...')
webhook.delete

import vanlo
vanlo.api_key = 'VANLO_API_KEY'

webhook = vanlo.Webhook.retrieve('hook_...')
webhook.delete()

require_once('/path/to/lib/vanlo.php');
\Vanlo\Vanlo::setApiKey('VANLO_API_KEY');

$webhook->delete();

using Vanlo;
ClientManager.SetCurrent("VANLO_API_KEY");

Webhook webhook = Webhook.Retrieve("hook_...");
webhook.Destroy();

Delete a Webhook by id.

The above command returns JSON structured like this:

{}

HTTP Request

DELETE https://www.vanlo.com/api/v1/webhooks/:id

Delete Webhook Request Parameters

Parameter	Example
id	hook_...

Handling Webhooks

When a webhook is triggered an event will be sent to the webhook endpoint via a POST request.

Webhook Event Parameters

Parameter	Example
id	evt_...
object	Event
description	tracker.updated
pending_urls	[http://example.com, http://other_example.com]
completed_urls	[http://example.com, http://other_example.com]
result	<Result>
created_at	2020-04-13T14:00:27.966Z
updated_at	2020-04-13T14:00:27.966Z

Webhook Event Result

Each event type will return a specific set of data in the result field of the webhook event.

tracker.updated

Parameter	Example
id	trk_...
object	Tracker
status	delivered
weight	1.2
carrier	USPS
user_id	111
finalized	true
is_return	false
signed_by	John Tester
created_at	2020-04-13T13:55:52Z
public_url	https://...
updated_at	2020-04-13T13:58:52Z
shipment_id	shp_...
status_detail	arrived_at_destination
tracking_code	948...
carrier_detail	<CarrierDetail>
tracking_details	<TrackingDetails>
est_delivery_date	2020-04-13T13:58:52Z

batch.updated

Parameter	Example
id	batch_...
object	Batch
state	purchased
status	<BatchStatus>
label_url	http://...
scan_form	<ScanForm>
shipments	1 item
created_at	2020-04-19T07:28:18.503Z
updated_at	2020-04-19T07:28:18.525Z
num_shipments	1

Errors

Here's an example of a 400 error response body:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid parameters were passed ...",
    "errors": [...]
  }
}

The Vanlo API uses the following error codes:

Error Code	Meaning
200 OK	The request was successful
201 Created	The request was successful and one or more resources was created
400 Bad Request	Request not processed due to client error
401 Unauthorized	Authentication is required and has failed
404 Not Found	The requested resource could not be found
422 Unprocessable Entity	The request was well-formed but unable to process the contained instructions
500 Application Error	Internal error

Please contact support@vanlo.com for assistance with errors.