Home

Awesome

Shoeboxed API

The Shoeboxed API is a full-featured RESTful web service that uses OAuth 2.0 for authentication.

Everything is self-serve: All you need is a Shoeboxed account to get started!

The Shoeboxed v2 API empowers developers to:

Libraries

Our API is only offered at this time as a HTTP web service. We do not provide native libraries or wrappers.

If you write a library for our API, we'd love to add a link! Please email the repo url to api@team.shoeboxed.com

Is this API production ready?

Yes, this API is production ready. We are "dogfooding" the API, and all Shoeboxed functionality is built by our developers using this API, so it is in everyone's interests to minimize breaking changes.

Getting Started

Authentication

We use OAuth 2 to authenticate all API requests. To get started, generate an OAuth 2.0 client_id and client_secret for your app:

  1. Sign up for Shoeboxed if you don't have an account
    • Contact us if you would like a limited-purpose dev account
  2. Generate Your OAuth 2 Credentials Once finished, be sure to copy your client_id and client_secret and store them somewhere secure.

Now that you have your own credentials, you may either:

If you want to get started as fast as possible making calls against our API, check out Step-by-Step OAuth 2.0 Guide

API endpoints

We use Swagger to provide an interactive API explorer that both documents the functionality of our API and allows you to make test calls directly from your browser.

Browse API Endpoints (you will leave GitHub)

Tip: Plug in a valid OAuth access token to make calls to our API from the documentation without leaving your browser.

Webhook notifications

We provide notifications for documents as they go through Shoeboxed processing. Fill in a desired notification URL for your API client, and any documents that belong to Shoeboxed users who have granted access to your application will trigger notifications of its status changes as it moves through the processing pipeline.

The notifications look like this:

{
    "documentId": "5319ef30e4b0aeb0ce0da7b0",
    "event": "processed",
    "token": "XWGAsFADpPjHg70GTIvhB7EpoOjsWIduMMoc8j8vhG94bJEAam",
    "signature": "miUJlR4KROB9GNfDpjIfR1Yje9qNXlK9yPkk4SMHsvU="
}

Event is one of created or processed.

Token is a 50-character random alphanumeric string; Signature is the HMAC of the token, using SHA-256 as the hash function and your API client secret as the key, and finally base64-encoded. This serves to verify that the notification is from Shoeboxed.

An example of computing the signature using the token and client secret using Python 2.7:

import hashlib, hmac, base64

token = b'provided token here'
secret = b'api client secret here'
signature = base64.b64encode(hmac.new(secret, token, digestmod=hashlib.sha256).digest())
print(signature)

Your application that receives the notification must return a status code in the 200s. If it does not, or if we encounter any other network error, then we will retry the notification up to 10 times, in increasing intervals. The exact times at which we will retry the notification are 2^n * 90, where n is the number of retries between 1 and 10; the resulting number is the number of seconds after the original notification at which we will attempt to retry.

Support

Feature requests? Bugs? Please file a GitHub issue.

We are also available over email: api@team.shoeboxed.com

API Terms of Service

View API Terms of Service

Legacy (v1) API Support

Warning: A .zip archive of the old, legacy API docs is provided for existing users of the legacy API. We strongly recommend you migrate to API v2 as soon as possible. Please email us at api@team.shoeboxed.com with any questions or concerns. OLD API docs archive. Right Click to Download.