NAV Navbar
javascript

Veho API Version 2

Welcome to the Veho API documentation! You can use the Veho API to programmatically create shipments and download shipping labels.

You're viewing Version 2 of the Veho API, which is our current version, meaning it's actively supported. Veho API V1 is deprecated.

Authentication

Authenticate a request:

import request from 'request';

function signRequestOptions(options) {
  // make sure headers object exists
  options.headers = options.headers || {};

  // put apikey in header
  options.headers['apikey'] = '00000000-0000-0000-0000-000000000000';
  options.headers['Content-Type'] = 'application/json';

  return options;
}

const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v2' });

const myData = { /* ... */ };

const options = signRequestOptions({
  method: 'POST',
  uri: '/packages',
  body: JSON.stringify(myData),
});

client(options, (err, response, body) => {
  if (err) {
    console.error('request failed', err);
  } else if (response.statusCode >= 400) {
    console.error('an error occurred', response);
  } else {
    // process body
  }
});

The Veho API requires an API key provided by Veho to access any endpoint.

Veho expects for the signature to be included in all API requests to the server in a header that looks like the following:

apikey: 00000000-0000-0000-0000-000000000000

Order and Package Objects

Orders and Packages are the two major objects you'll be working with, and they go together like toast and avocado! The Order is the container for any number of Packages going to the same recipient and address. An Order can have a single Package - in fact, most probably will - but like avocado on toast, you can add as my packages to an order as you like!

Order Object

An order with two packages:


{
  "_id": "5cxKLWAqtZhbNFe9y",
  "destination": {
    "street": "301 Cobblestone Way",
    "city": "Bedrock",
    "state": "CO",
    "zipCode": "80302"
  },
  "serviceClass": "nextDay",
  "recipient": "Fred Flintstone",
  "externalId": "abc-123",
  "rate": 600,
  "createdAt": "2019-01-23T00:35:50.788Z",
  "orderTrackingId": "5CSKLW",
  "packages": [
    {
      "_id": "GqN8v5wvGNxmnFu4Y",
      "externalId": "myPackageId1",
      "length": 12,
      "width": 10,
      "height": 9,
      "weight": 25,
      "declaredValue": 7500,
      "signatureRequired": true,
      "orderId": "5cxKLWAqtZhbNFe9y",
      "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.pdf",
      "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.png",
      "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.zpl",
      "currentState": "created",
      "createdAt": "2019-01-23T00:35:50.796Z",
      "barCode": "GqN8v5wvGNxmnFu4Y",
      "eventLog": [
        {
          "eventType": "created",
          "timestamp": "2019-01-23T00:35:50.796Z"
        }
      ],
    },
    {
      "_id": "yuyGF9EeACeH6f8ch",
      "externalId": "myPackageId2",
      "orderId": "5cxKLWAqtZhbNFe9y",
      "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/yuyGF9EeACeH6f8ch.pdf",
      "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/yuyGF9EeACeH6f8ch.png",
      "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/yuyGF9EeACeH6f8ch.zpl",
      "currentState": "created",
      "signatureRequired": false,
      "createdAt": "2019-01-23T00:35:50.808Z",
      "barCode": "yuyGF9EeACeH6f8ch",
      "eventLog": [
        {
          "eventType": "created",
          "timestamp": "2019-01-23T00:35:50.808Z"
        }
      ],
    }
  ]
}

The Order object has the following structure:

Parameter Type Description
destination Destination (required) Delivery address (description below).
recipient  String (required) Full name of recipient.
serviceClass String Requested class of service, currently sameDay or nextDay. Default: nextDay.
phone  String Recipient's phone number (used for SMS).
externalId String Any ID you want to associate with this order, e.g. your order ID.
instructions  String Any additional delivery instructions provided by recipient to assist driver with delivery.
packages Array<Package> Array of packages (see package below).
orderTrackingId String Alphanumeric identifier used by package recipient to track their package. See Tracker.

Destination object

The Destination object describes an address, and has the following structure:

Parameter  Type Description
street String (required) street address
apartment String apartment number, suite number, or any info on the second line of an address
city  String (required) city of the delivery address
zipCode String (required) ZIP code of the address (view our service area)
state String (required) state of the address
(can be 2 letter postal code, or full state name)
country String 2 letter ISO country code for the address

Package object

A package:


{
  "_id": "GqN8v5wvGNxmnFu4Y",
  "externalId": "myPackageId1",
  "length": 12,
  "width": 10,
  "height": 9,
  "weight": 25,
  "declaredValue": 7500,
  "signatureRequired": true,
  "orderId": "5cxKLWAqtZhbNFe9y",
  "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.pdf",
  "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.png",
  "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.zpl",
  "currentState": "created",
  "createdAt": "2019-01-23T00:35:50.796Z",
  "barCode": "GqN8v5wvGNxmnFu4Y",
  "eventLog": [
    {
      "eventType": "created",
      "timestamp": "2019-01-23T00:35:50.796Z"
    }
  ]
}

The Package object is associated with an order. An order may have one or many packages. Package has the following structure:

Parameter  Type Description
signatureRequired Boolean Specify whether recipient has to sign for this package. Default: false.
length Number Length (inches) of the package.
width Number Width (inches) of the package.
height Number Height (inches) of the package.
weight Number Weight (pounds) of the package, in pounds.
externalId String Any ID you want to associate with this package. Note that you should associate an Order ID with the Order object.
declaredValue Number Declared value of package, in USD pennies (5000 is $50 USD).
description String Description of the package.
zplShippingLabelLink String Link to zpl shipping label file.
pdfShippingLabelLink String Link to pdf shipping label file.
pngShippingLabelLink String Link to png shipping label file.
eventLog Array<event> Array of events for this package.

Event object

eventType is one of the following:


[
    'created',
    'pending',
    'notFound',
    'pickedUpFromClient',
    'droppedOffAtVeho',
    'pickedUpFromVeho',
    'delivered',
    'returned'
]

The eventLog object represents an event in the lifecycle of the package:

Parameter  Type Description
eventType String enum representing the event that occurred
timestamp DateTime time at which the event occurred

Orders

Create an order

Create an order with one package:

import request from 'request';

const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v2' });

const order = {
  "destination": {
    "street": "301 Cobblestone Way",
    "city": "Bedrock",
    "state": "CO",
    "zipCode": "80302"
  },
  "recipient": "Fred Flintstone",
  "serviceClass": "nextDay",
  "phone": "(303) 456-7788",
  "externalId": "abc-123",
  "instructions": "Leave inside screen door",
  "packageCount": 1
};

const options = signRequestOptions({
  method: 'POST',
  uri: '/orders',
  body: JSON.stringify(order),
});

client(options, (err, response, body) => {
  if (err) {
    console.error('request failed', err);
  } else if (response.statusCode >= 400) {
    console.error('error creating order', body);
  } else {
    console.log(body);
  }
});

The above command returns a request similar to this this:

{
    "_id": "TuN75hYYBicRsaLWo",
    "destination": {
      "street": "301 Cobblestone Way",
      "city": "Bedrock",
      "state": "CO",
      "zipCode": "80302"
    },
    "serviceClass": "nextDay",
    "recipient": "Fred Flintstone",
    "phone": "(303) 456-7788",
    "instructions": "Leave inside screen door",
    "rate": 600,
    "createdAt": "2019-01-23T00:13:00.289Z",
    "orderTrackingId": "5CSKLW",
    "externalId": "abc-123",
    "packages": [
      {
        "_id": "gaaqrh3DcCGbGECuT",
        "orderId": "TuN75hYYBicRsaLWo",
        "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/gaaqrh3DcCGbGECuT.pdf",
        "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/gaaqrh3DcCGbGECuT.png",
        "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/gaaqrh3DcCGbGECuT.zpl",
        "currentState": "created",
        "signatureRequired": false,
        "createdAt": "2019-01-23T00:13:00.297Z",
        "barCode": "gaaqrh3DcCGbGECuT"
      }
    ]
}

Create an order with two packages and specify some package details:

import request from 'request';

const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v2' });

const order = {
  "destination": {
    "street": "301 Cobblestone Way",
    "city": "Bedrock",
    "state": "CO",
    "zipCode": "80302"
  },
  "recipient": "Fred Flintstone",
  "externalId": "abc-123",
  "packages": [
    {
      "externalId": "myPackageId1",
      "length" : 12,
      "width": 10,
      "height": 9,
      "weight": 25,
      "declaredValue": 7500,
      "signatureRequired": true
    },
    {
      "externalId": "myPackageId2"
    }
  ]
}

const options = signRequestOptions({
  method: 'POST',
  uri: '/orders',
  body: JSON.stringify(order),
});

client(options, (err, response, body) => {
  if (err) {
    console.error('request failed', err);
  } else if (response.statusCode >= 400) {
    console.error('error creating order', body);
  } else {
    console.log(body);
  }
});

The above command will return a JSON response similar to this:


{
  "_id": "5cxKLWAqtZhbNFe9y",
  "destination": {
    "street": "301 Cobblestone Way",
    "city": "Bedrock",
    "state": "CO",
    "zipCode": "80302"
  },
  "serviceClass": "nextDay",
  "recipient": "Fred Flintstone",
  "externalId": "abc-123",
  "rate": 600,
  "createdAt": "2019-01-23T00:35:50.788Z",
  "orderTrackingId": "5CSKLW",
  "packages": [
    {
      "_id": "GqN8v5wvGNxmnFu4Y",
      "externalId": "myPackageId1",
      "length": 12,
      "width": 10,
      "height": 9,
      "weight": 25,
      "declaredValue": 7500,
      "signatureRequired": true,
      "orderId": "5cxKLWAqtZhbNFe9y",
      "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.pdf",
      "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.png",
      "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/GqN8v5wvGNxmnFu4Y.zpl",
      "currentState": "created",
      "scannedByClient": false,
      "createdAt": "2019-01-23T00:35:50.796Z",
      "barCode": "GqN8v5wvGNxmnFu4Y"
    },
    {
      "_id": "yuyGF9EeACeH6f8ch",
      "externalId": "myPackageId2",
      "orderId": "5cxKLWAqtZhbNFe9y",
      "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/yuyGF9EeACeH6f8ch.pdf",
      "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/yuyGF9EeACeH6f8ch.png",
      "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/yuyGF9EeACeH6f8ch.zpl",
      "currentState": "created",
      "signatureRequired": false,
      "scannedByClient": false,
      "createdAt": "2019-01-23T00:35:50.808Z",
      "barCode": "yuyGF9EeACeH6f8ch"
    }
  ]
}

This endpoint creates a new order. This endpoint should be used by a client upon order completion or fulfillment of an item in order to to notify Veho that there are packages to be shipped, and to obtain a barcode and/or shipping label from Veho.

HTTP Request

POST https://api-basic.shipveho.com/v2/orders

Request body

Order object

The Order object has the following structure:

Parameter Type Description
destination Destination (required) Delivery address (description below).
recipient  String (required) Full name of recipient.
serviceClass String Requested class of service, currently sameDay or nextDay. Default: nextDay.
phone  String Recipient's phone number (used for SMS).
externalId String Any ID you want to associate with this order, e.g. your order ID.
instructions  String Any additional delivery instructions provided by recipient to assist driver with delivery.
packageCount Number Number of packages associated with this order. Use this field to create one or more packages without supplying additional information. To include package-specific information, use the packages field instead.
packages Array<Package> Array of packages (see package below). If you don't need to describe package-specific information, use the packageCount field instead.

Destination object

The Destination object describes an address, and has the following structure:

Parameter  Type Description
street String (required) street address
apartment String apartment number, suite number, or any info on the second line of an address
city  String (required) city of the delivery address
zipCode String (required) ZIP code of the address (view our service area)
state String (required) state of the address
(can be 2 letter postal code, or full state name)
country String 2 letter ISO country code for the address

Package object

The Package object is associated with an order. An order may have one or many packages. Package has the following structure:

Parameter  Type Description
signatureRequired Boolean Specify whether recipient has to sign for this package. Default: false.
length Number Length (inches) of the package.
width Number Width (inches) of the package.
height Number Height (inches) of the package.
weight Number Weight (pounds) of the package, in pounds.
externalId String Any ID you want to associate with this package. Note that you should associate an Order ID with the Order object.
declaredValue Number Declared value of package, in USD pennies (5000 is $50 USD).
description String Description of the package.

Returns

Creating an order returns the order object, including all inputted data, package data, any optional data that has default values, and some server-generated data:

Parameter  Type Description
_id String Package UID.
recipient String Full name of recipient.
destination Destination Delivery address.
currentState String Current state of the package.
barCode String content of the Code128 bar code the package will have
zplShippingLabelLink String Link to zpl shipping label file.
pdfShippingLabelLink String Link to pdf shipping label file.
pngShippingLabelLink String Link to png shipping label file.
rate Number Rate client will be charged, in USD pennies (1000 is $10 USD).
instructions String Any additional delivery instructions provided by recipient to assist driver with delivery.
orderTrackingId String Alphanumeric identifier used by package recipient to track their package. See Tracker.
packages Array<Package> Package(s) associated with this Order.

Get an order

import request from 'request';

const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v2' });

const options = signRequestOptions({
  method: 'GET',
  uri: '/orders/XSjuNSWgq7K8KKTrc'
});

client(options, (err, response, body) => {
  if (err) {
    console.error('request failed', err);
  } else if (response.statusCode >= 400) {
    console.error('error retrieving order', body);
  } else {
    console.log(body);
  }
});

The above command returns JSON structured like this:

{
    "_id": "XSjuNSWgq7K8KKTrc",
    "destination": {
        "street": "1900 Grove St",
        "city": "Boulder",
        "state": "CO",
        "zipCode": "80302"
    },
    "serviceClass": "nextDay",
    "recipient": "Linda Lee",
    "rate": 600,
    "createdAt": "2019-01-22T22:44:30.667Z",
    "orderTrackingId": "5CSKLW",
    "packages": [
        {
            "_id": "QALWadntAhLH9y6DB",
            "orderId": "XSjuNSWgq7K8KKTrc",
            "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/QALWadntAhLH9y6DB.pdf",
            "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/QALWadntAhLH9y6DB.png",
            "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/QALWadntAhLH9y6DB.zpl",
            "currentState": "created",
            "signatureRequired": false,
            "scannedByClient": false,
            "createdAt": "2019-01-22T22:44:30.675Z",
            "barCode": "QALWadntAhLH9y6DB"
        }
    ]
}

This endpoint retrieves an order and its packages.

HTTP Request

GET https://api-basic.shipveho.com/v2/orders/<ID>

URL Parameters

Parameter Description
ID _id of the order to retrieve

Packages

Get a package

import request from 'request';

const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v2' });

const options = signRequestOptions({
  method: 'GET',
  uri: '/packages/PiMwXg7Zz98WQTGL3'
});

client(options, (err, response, body) => {
  if (err) {
    console.error('request failed', err);
  } else if (response.statusCode >= 400) {
    console.error('error retrieving package', body);
  } else {
    console.log(`package "${body._id}" created`);
  }
});

The above command returns JSON structured like this:

{
    "_id": "PiMwXg7Zz98WQTGL3",
    "orderId": "XSjuNSWgq7K8KKTrc",
    "pdfShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/PiMwXg7Zz98WQTGL3.pdf",
    "pngShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/PiMwXg7Zz98WQTGL3.png",
    "zplShippingLabelLink": "https://api-basic.shipveho.com/v2/labels/PiMwXg7Zz98WQTGL3.zpl",
    "currentState": "created",
    "signatureRequired": false,
    "createdAt": "2019-01-22T22:44:30.710Z",
    "barCode": "PiMwXg7Zz98WQTGL3"
}

This endpoint retrieves all details of an existing package.

HTTP Request

GET https://api-basic.shipveho.com/v2/packages/<ID>

URL Parameters

Parameter Description
ID _id of the package to retrieve

Query Parameters

Parameter Default Description

Errors

The Veho API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized -- The header did not include a valid apikey.
403 Forbidden -- The requested resource cannot be accessed with this app ID.
404 Not Found -- The requested resource could not be found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
422 Unprocessable Entity -- The request entity is syntactically correct but semantically incorrect.
429 Too Many Requests
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Tracker

Tracker url

A customer-facing tracker can be constructed in the following way:


const trackerUrl = `https://track.shipveho.com/#/barcode/${package.barCode}`;

package.barCode may be used to construct a customer-facing tracking url. The url displays a web application that displays a package's status, and allows a customer to provide the Veho driver with instructions.

Webhooks

Webhook Events

Webhooks can be sent for the following events:


[
    'package.created',
    'package.pickedUpFromClient',
    'package.droppedOffAtVeho',
    'package.pickedUpFromVeho',
    'package.delivered'
]

Veho has webhooks available for developers to receive updates when events occur on their shipments. Webhooks are in beta and there is currently no API or GUI interface to create or manage webhooks. If you are a current client and would like to set up one or more webhookEndpoints, please contact your account manager or product@shipveho.com and we will assist you in building your webhooks!

Webhook Event Object

An example of the http request dispatched upon the occurrence of an event:


{
  "headers": {
    "Content-Type": "application/json",
    "X-Veho-Time": "2019-04-19T22:09:23.894Z",
    "X-Veho-Hmac-Sha256": "5a2cfd7178f486ec269623e097b62194e5d9b4ad18eb28d57ebded23ef92af8e"
  },
  "method": "POST",
  "body": {
    "package": {
      "orderId": "wm33ZW2EQrTpqbfH2",
      "pdfShippingLabelLink": "http://api-basic.shipveho.com/v2/labels/A2L3jBrkJb4xrPht8.pdf",
      "pngShippingLabelLink": "http://api-basic.shipveho.com/v2/labels/A2L3jBrkJb4xrPht8.png",
      "zplShippingLabelLink": "http://api-basic.shipveho.com/v2/labels/A2L3jBrkJb4xrPht8.zpl",
      "eventLog": [{
        "eventType": "created",
        "timestamp": "2019-04-19T22:09:23.882Z"
      }],
      "lastEvent": "created",
      "signatureRequired": false,
      "createdAt": "2019-04-19T22:09:23.881Z",
      "_id": "A2L3jBrkJb4xrPht8",
      "barCode": "A2L3jBrkJb4xrPht8"
    },
    "order": {
      "_id": "wm33ZW2EQrTpqbfH2",
      "destination": {
        "street": "301 Cobblestone Way",
        "city": "Bedrock",
        "state": "CO",
        "zipCode": "80302"
      },
      "serviceClass": "nextDay",
      "recipient": "Fred Flintstone",
      "phone": "(303) 456-7788",
      "instructions": "Leave inside screen door",
      "externalId": "abc-123",
      "rate": 600,
      "createdAt": "2019-04-19T22:09:23.866Z"
    },
    "event": "package.created",
    "webhookEndpoint": {
      "_id": "5cb76d250abc3ced20e203bf",
      "events": ["package.created"],
      "clientId": "iPudwdiJYmhRN3dah",
      "endpoint":"https://example-webhook-endpoint.shipveho.com"
    }
  }
}

The request is sent as an http POST and the body includes the package on which the event occurred, the order associated with the package, the event, and the webhookEndpoint object that generated the request.

Checking webhook signatures

An example of how to verify webhook signature:


import crypto from 'crypto';

const req = // incoming webhook event http request
const timestamp = req.headers['x-veho-time'];
const hash = crypto.createHmac('SHA256', apikey);
hash.update(`${timestamp}.${JSON.stringify(req.body)}`);
if (req.headers['x-veho-hmac-sha256'] === hash.digest('hex')) {
  console.log('Signature verified');
};

To verify the authenticity of a Veho webhook event:

  1. Extract the timestamp from the signature.
  2. Concatenate the timestamp, the . character, and the JSON payload (the request's body).
  3. Compute an HMAC with the SHA256 hash function, using your apikey as the key and the concatenated string from (2) as the message.
  4. Compare the x-veho-hmac-sha256 header param with your calculated hash. If the signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

WebhookEndpoint Object

An example of a webhookEndpoint:


"webhookEndpoint": {
  "_id": "5cb76d250abc3ced20e203bf",
  "events": ["package.created"],
  "clientId": "iPudwdiJYmhRN3dah",
  "endpoint":"https://example-webhook-endpoint.shipveho.com"
}

The webhookEndpoint object represents an endpoint that will receive an event object whenever that event occurs on a package associated with that client. There are currently no ways to create or modify the webhookEndpoint directly - please contact your account manager or product@shipveho.com and we will assist you in building your webhooks!

Parameter  Type Description
events Array<String> an array of strings matching webhook events
endpoint String the URL the webhook event will dispatch to