Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Shoeboxed API implementation
tag: v0.3.0

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


An implementation of the Shoeboxed ( API. Consult the Shoeboxed API documentation ( for details of API operations.

WARNING WARNING WARNING: This gem is not ready for production use yet. See the note below about partial data retrieval. It also needs more testing with actual Shoeboxed accounts instead of mocked data. I plan to release a useable version by 12/15/11.

What's Implemented

Connecting to Shoeboxed

In general, using Shoeboxed requires three things:

  • An application name
  • An application token
  • A user token

The first two are supplied by Shoeboxed - you can find them in your Account & Settings page on the Shoeboxed site under "API Keys and Info." The third must be retrieved by running the user through an authentication process.

Start the process by initializing shoehorn with your application information:

connection ='MyAppName', 'my_app_token', '', {:param => 'value'})

The third and fourth parameters define the callback URL that your application must listen to for the user token. You can supply a base URL and a set of querystring parameters that will be returned.

Next, retrieve connection.authentication_url from shoehorn. Send your user to this URL. If they choose to authorize your application's use of their Shoeboxed data, you'll get a call back on the supplied URL with your supplied parameters plus two more:

  • tkn will be the user token
  • uname will be the username on Shoeboxed

Finally, save the user token on your shoehorn connection. This sets the user context for all subsequent shoehorn calls.

connection.user_token = tkn

See for further details on the Shoeboxed authentication process.

Retrieving data

After successfully authenticating, you can retrieve the user's Shoeboxed data from collections on the connection:


These collections are lazily initialized when they are first accessed. Each also supports a refresh method to update the data from Shoeboxed. Within the collections you'll find individual objects - Bill, BusinessCard, Category, ExpenseReport, OtherDocument, Receipt - containing the details of the data.

IMPORTANT - In the 0.3 release of shoehorn, these collections ONLY contain the first 50 documents of each type. This makes the library largely unusable for large accounts. Full pagination support is coming soon!

If you know the ID of a particular document on Shoeboxed, you can retrieve it directly with the find_by_id method on the appropriate collection:

bill = connection.bills.find_by_id("123884")

NOTE: The find_by_id method is not supported on expense reports.

Utility methods

Some other parts of the Shoeboxed API are also covered by this gem:

  • BusinessCards
    • estimate_pdf_business_card_report - returns the estimated number of cards and pages for exporting business cards as a PDF.
    • generate_pdf_business_card_report - Returns a URL for one-time download of business cards as a PDF.
    • get_business_card_exports - Returns a hash of export options and whether they are enabled.
    • notify_preferences - Get or set the user's auto-share mode.
    • get_viral_business_card_email_text
    • auto_share_contact_details - Get or set the user's contact information that is sent out with business cards

What's Missing

  • Transparent pagination of large collections
  • Upload support
  • Cover sheet support
  • Ruby native data types for things like dates
  • Live sandbox testing (This is not yet implemented by Shoeboxed)

Testing Shoehorn

Some of the tests depend on a live connection to Shoeboxed. To set this up, you must make a copy of test/shoehorn_credentials.sample.yml to test/shoehorn_credentials.yml and fill in the required information.


Mike Gunderloy,

Thanks to for previous hard work on the Shoeboxed API. Some portions of this code originated with rshoeboxed.

Public repo:

Something went wrong with that request. Please try again.