NAV Navbar
javascript
  • Veho API Version 1
  • Authentication
  • Packages
  • Errors
  • Veho API Version 1

    Welcome to Veho API Version 1. You can use our API to programmatically create shipments and download shipping labels.

    Authentication

    To authenticate a POST request to /packages, use this code:

    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/v1' });
    
    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', body);
      } else {
        // process body
      }
    });
    

    The Veho Basic 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

    Packages

    Create a new package

    import request from 'request';
    
    const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v1' });
    
    const new_package = {
        destination: {
            street: "1002 Walnut St",
            apartment: "Suite 200",
            city: "Boulder",
            state: "CO",
            zipCode: "80302"
        },
        phone: "555-555-5555",
        recipient: "John Smith",
        instructions: "Leave on front porch behind railing. Beware of dog!",
        serviceClass: "nextDay",
        signatureRequired: "true",
        declaredValue: 5000
    };
    
    const options = signRequestOptions({
      method: 'POST',
      uri: '/packages',
      body: JSON.stringify(new_package),
    });
    
    client(options, (err, response, body) => {
      if (err) {
        console.error('request failed', err);
      } else if (response.statusCode >= 400) {
        console.error('error creating package', body);
      } else {
        console.log(`package "${body._id}" created`);
      }
    });
    

    The above command returns JSON structured like this:

    {
        "_id": "BSG6XZQrgwieFFJPx",
        "destination": {
            "street": "1002 Walnut St",
            "apartment": "Suite 200",
            "city": "Boulder",
            "state": "CO",
            "zipCode": "80302"
        },
        "recipient": "John Smith",
        "phone": "555-555-5555",
        "instructions": "Leave on front porch behind railing. Beware of dog!",
        "serviceClass": "nextDay",
        "signatureRequired": true,
        "scannedByClient": false,
        "createdAt": "2018-07-29T01:09:31.690Z",
        "currentState": "created",
        "barcode": "veho_id_BSG6XZQrgwieFFJPx",
        "zplShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.zpl",
        "pdfShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.pdf",
        "pngShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.png",
        "rate": 1000,
        "declaredValue": 5000
    }
    

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

    HTTP Request

    POST https://api-basic.shipveho.com/v1/packages

    Request body

    Package Object

    Parameter Type Description
    destination Destination address information for delivery (description below)
    serviceClass string requested class of service, currently sameDay or nextDay (defaults to nextDay)
    recipient  string  full name of the recipient
    phone  string optional phone number of the recipient (used for SMS)
    instructions  string  optional any additional delivery instructions provided by recipient to assist driver with delivery
    signatureRequired boolean optional set to true if the recipient has to sign for this packages (defaults to false)
    externalId  string  optional any ID you want to have stored with this stop.
    (f.e. an order number)
    width  integer optional width of the package, in in
    height  integer optional height of the package, in in
    length  integer optional length of the package, in in
    weight  integer  optional weight of the package, in lbs
    declaredValue Number optional declared value of shipment, in USD pennies (5000 is $50 USD)

    Destination object

    Destination is an address object in the following shape:

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

    Returns

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

    Parameter  Type Description
    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)

    Get a package

    import request from 'request';
    
    const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v1' });
    
    const options = signRequestOptions({
      method: 'GET',
      uri: '/packages/BSG6XZQrgwieFFJPx'
    });
    
    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": "BSG6XZQrgwieFFJPx",
        "destination": {
            "street": "1002 Walnut St",
            "apartment": "Suite 200",
            "city": "Boulder",
            "state": "CO",
            "zipCode": "80302"
        },
        "phone": "555-555-5555",
        "recipient": "John Smith",
        "instructions": "Leave on front porch behind railing. Beware of dog!",
        "serviceClass": "nextDay",
        "signatureRequired": true,
        "scannedByClient": false,
        "createdAt": "2018-07-29T02:41:36.151Z",
        "currentState": "created",
        "barcode": "veho_id_BSG6XZQrgwieFFJPx",
        "zplShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.zpl",
        "pdfShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.pdf",
        "pngShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.png",
        "rate": 1000,
        "declaredValue": 5000
    }
    

    This endpoint retrieves all details of an existing package.

    HTTP Request

    GET https://api-basic.shipveho.com/v1/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.