Cashboard API

Introduction

Cashboard is time tracking & invoicing software for small businesses.

The Cashboard API allows programmers to integrate Cashboard with other applications and data.

It serves XML and JSON over HTTPS (HTTPS-POX / POJ), using RESTful principles.
We've adhered to the REST design standards as much as possible - but deviate where necessary.

Authentication

In order to use the Cashboard API you must have the proper auth credentials.

You can obtain a Cashboard API key by logging into your Cashboard account, then navigating to the Settings > Your Info screen. Your API key is shown on the right-hand side of the page.

The Cashboard API is available to employees of your company only.
Your clients may not use the Cashboard API.

Authentication is handled via HTTP Basic Auth over HTTPS.
Use your Cashboard subdomain as the username, and your API Key as the password.
Every request except Account Creation must contain the Authorization HTTP header.

Authentication Responses

HTTP 401 (UNAUTHORIZED) - Your request doesn't contain the proper Authentication header.
HTTP 401 (UNAUTHORIZED) - You can't login because your login has been archived.
HTTP 402 (PAYMENT REQUIRED) - Your account has been disabled due to non-payment.

Permissions

Users of the API will have different levels of access to the data within.

Administrators can do anything with the API and see all fields
What employees can do will be determined by their access level, as set in the Cashboard Application UI

Certain fields may be hidden from view from employees, such as dollar amounts
Certain actions will not be available to employees and will return a HTTP 403 (FORBIDDEN) response

Your client application should be able to handle empty values for amounts and 403 responses properly.

Making Requests

From your browser

To get started, you can poke at the Cashboard API with a normal browser, such as Firefox. Firefox is a good choice for this task (as it renders the XML tags), instead of something like Safari (which dumps the content to your screen).

To browse the Cashboard API, simply append .xml to any of the resource URLs. For instance, if you'd like to get a list of all expenses for your account the URL would be /expenses.xml. You will be prompted for your authentication credentials, as explained above.

From the command line or scripts

You must set both the Content-Type and Accept headers to 'application/xml' when interacting with the API from your scripts or the command line. If you don't do this, your request will be rejected.

Here's a simple example with the command line program 'curl'.

curl \
-H 'Accept: application/xml' \
-H 'Content-Type: application/xml' \
-u CASHBOARD_SUBDOMAIN:API_KEY \
http://api.cashboardapp.com/expenses

Supported Content Types

* Supported on actions where noted by the documentation.

XML	application/xml
JSON	application/json
*PDF	application/pdf
*HTML	text/html

We also fully support JSON-P for cross domain HTML5 requests. Simply add the "callback" or "variable" querystring parameter to the URL.

Writing to the API

Writing to the API is handled with HTTP POST for creating resources, and HTTP PUT for updating them.

Here's a simple example of creating an expense record, again with curl.

curl \
-H 'Accept: application/xml' \
-H 'Content-Type: application/xml' \
-u CASHBOARD_SUBDOMAIN:API_KEY \
-d '<expense><amount>10.00</amount></expense>' \
http://api.cashboardapp.com/expenses

Responses from the server

Responses will be returned in the format you request via the Accept and Content-Type headers.

POST

POST requests will create a resource.

Successful creation requests will return HTTP response code 201 (CREATED) and data representation of the resource created.

<?xml version="1.0" encoding="UTF-8"?>
<expense>
  <link rel="self" href="http://api.cashboardapp.com/expenses/1234567" />
  <id>1234567</id>
  <amount>10.00</amount>
  <category></category>
  <created_on></created_on>
  <description></description>
  <invoice_line_item_id></invoice_line_item_id>
  <is_billable>false</is_billable>
  <payee_id></payee_id>
  <payee_type></payee_type>
  <person_id></person_id>
  <project_id></project_id>
</expense>

As you can see from the dummy data above, a LINK tag will be returned for all resources that contains the URL used to access it. You can use this URL to perform further actions on that resource, such as updating or deleting.

Unsuccessful creation requests will return HTTP response code 400 (BAD REQUEST), and data explaining what errors there are on the resource you attempted to create.

Here's an example of a response to an unsuccessful account creation request.

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error field="admin_password">Admin password This field is required.</error>
  <error field="admin_email_address">Admin email address This field is required.</error>
</errors></pre></code>

GET

Successful get requests will return HTTP response code 200 (SUCCESS) and data representation of that resource.

Unsuccessful get requests will return HTTP response code 404 (NOT FOUND).

PUT

Successful put requests will return HTTP response code 200 (SUCCESS) and data representation of that resource.

Unsuccessful get requests will return

HTTP response code 404 (NOT FOUND) if the resource for the URL provided is not found
HTTP response code 400 (BAD REQUEST) and a data representation of the errors if the resource you're trying to update is invalid

DELETE

Successful put requests will return HTTP response code 200 (SUCCESS). No data will be returned.

HTTP response code 404 (NOT FOUND) if the resource for the URL provided is not found
HTTP response code 400 (BAD REQUEST) if the resource can't be deleted