Billy API v2 Documentation

Billy’s new API is a JSON-based REST API. Our webapp uses the exact same API – which is your guarantee that the API will always support full functionality, and will generally be nice to work with. We take our own medicine!

If you have any questions or feedback (we love feedback!), please don’t hesitate to ask us on Twitter, or mail us at [email protected]. 

Table of Contents

• Endpoint
• Authentication
• Conventions
• Relationships
• Paging
• Filtering
• Sorting
• Code examples
• Use case examples
• Resource documentation

Endpoint

The API is located at https://api.billyapp.com/.

All requests must use SSL.

Authentication

We currently support two authentication methods with the API.

OAuth access tokens

Here’s how to obtain an access token for your company:

• Log into your account on app.billyapp.com.
• Go to Settings -> Access tokens.
• Click Create access token.
• Enter a descriptive name for your token, so you can easily identify it later. Then hit the Save button.
• Hover over the newly-generated access token and click the magnifier icon to show it clearly.
• The token will now be selected in a text field, inside a lightbox.

All you have to do now is put this token in a X-Access-Token header. See Code examples for a complete example.

The tokens you create under Settings -> Access tokens are tied to that company only. If you have multiple companies, you’ll need a separate token for each one. Tokens are permanent – the don’t expire.

We plan to support a 3-legged OAuth solution eventually.

HTTP basic auth

You can use your normal email and password for authentication HTTP Basic Auth. You can try it right now, if you like. Just navigate to https://api.billyapp.com/v2/user. Enter your email and password in the browser’s credentials form, and you’ll see your user as a JSON document.

Conventions

Billy’s API is very consistent; we use the same conventions for all resources. Generally speaking, there are 5 ways to interact with a resource: Get one item, list, create, update and delete.

A resource is always accessed through its pluralized name. For example, you can access invoices through /v2/invoices.

In the examples that follow, we’ll use the invoices resource – but the exact same pattern applies to all resources.

Getting a single record

When getting a single record, you should use GET /v2/invoices/:id (where :id denotes a dynamic slug, and should be replaced by a real invoice ID). The response will be a JSON document with a root key named after the singular name containing the requested record. Invoice example:

{
  "invoice": {
    "id": "3mIN9EbDEeOg8QgAJ4gM",
    "invoiceNo": 41,
    ...
  }
}

Listing a resource

Use GET /v2/invoices. The response will be a JSON document with a root key named after the pluralized designation and containing an array of found records. Invoice example:

{
  "invoices": [
    {
      "id": "3mIN9EbDEeOg8QgAJ4gM",
      "invoiceNo": 41,
      ...
    },
    {
      "id": "4LmaTkbDEeOg8QgAJ4to",
      "invoiceNo": 42,
      ...
    }
  ]
}

Creating a record

Use POST /v2/invoices. The request body should be a JSON document containing a single root key named after the singular name, and should be a hash of record properties. Invoice example:

{
  "invoice": {
    "invoiceNo": 41,
    "entryDate": "2013-11-14",
    ...
  }
}

See more about the response body in the section Responses to create/update/delete requests. You can get the ID of the newly created record by getting invoices.0.id in the returned JSON document.

Updating a record

Use PUT /v2/invoices/:id. The request body should be a JSON document containing a single root key named after the singular name, and should be a hash of record properties. The hash does not need to include the record’s ID – if it does, though, it must be exactly the same ID you used in the URL. You can’t change a record’s ID. Invoice example:

{
  "invoice": {
    "contactMessage": 41,
    ...
  }
}

Only properties that you set in the invoice hash will be updated. Properties that are left out will be considered as if they are the same. So if all you need to do is to update the contactMessage property, then you don’t need to include any other properties.

The response works the same as with a POST request.

Deleting a record

Use DELETE /v2/invoices/:id. The request should not have a body.

DELETE requests are idempotent, meaning that if you try to DELETE the same record more than once (or delete any other non-existing ID), you will still receive a 200 OK response.

See more about the response body in the section ‘Responses to create/update/delete requests’.

Responses to create/update/delete requests

When you make POST, PUT, PATCH or DELETE requests to the API, the response will always include all records that changed because of the request. The record you created/updated will of course be included. Example: When you create an invoiceLine for an existing invoice, the amount field on the invoice will also be changed. So a POST /v2/invoiceLines would return something like:

{
  "invoices": [
    {
      "id": "3mIN9EbDEeOg8QgAJ4gM",
      "amount": 200,
      ...
    }
  ],
  invoiceLines: [
    {
      "id": "cgYxHZWCSfajDIvj9Q8yRQ",
      "invoiceId": "3mIN9EbDEeOg8QgAJ4gM",
      ...
    }
  ]
}

The IDs of deleted records will be accessible through the meta.deletedRecords property. Example: When requesting DELETE /v2/invoices/1234, the response will be:

{
  "meta": {
    "deletedRecords": {
      "invoices": [
        "1234"
      ]
    }
  }
}

Note that some PUT requests may delete records, too – for example, when you overwrite a record’s has-many relationship using an embedded array of child records.

Relationships

The API is smart about relationships. Many resources have relationships, and we distinguish between two kinds of relationships:

• Belongs-to: A record of resource A has an ID that points to a record of resource B. Example: invoice records have a contactId property which points to a contact record.
• Has-many: A record of resource A has zero or more records of resource B that point to it. Example: invoice records have zero or more invoiceLine records that have an invoiceId property, which points back. A has-many relationship always implies a belongs-to relationship on the inverse resource.

Normally, when you GET a resource that has relationships, the belongs-to relationship will be presented as the name of the property, suffixed with Id and containing the ID. If you GET /v2/invoices/123 and it responds with a "contactId": "987", you can get the contact by requesting GET /v2/contacts/987. Has-many relationships won’t be in the request, by default.

Requesting sideloaded or embedded records

You can include relationships by adding an include parameter to your GET request. The value of the include parameter should be in the form resource.property:mode[,resource.property:mode,...], where resource is the name of a resource, property is the name of a property of that resource, and mode is either sideload (default if the : part is omitted) or embed. You can include multiple relationships by separating them with ,.

Example: You can load invoices with its invoiceLines embedded, its contacts sideloaded, and the contact’s country embedded by doing GET /invoices?include=invoice.lines:embed,invoice.contact:sideload,contact.country:embed. The response will be something like:

{
  "invoices: [
    {
      "id": "invoice1",
      "contactId": "contact1",
      ...
      "lines": [
        {
          "id": "line1",
          ...
        },
        {
          "id": "line2",
          ...
        }
      ]
    }
  ],
  "contacts: [
    {
      "id": "contact1",
      "country": {
        "id": "DK",
        "name": "Denmark",
        ...
      },
      ...
    }
  ]
}

When sideloading belongs-to relationships, the name of the key is the singular name of the resource, suffixed with Id (like the default behavior), and each sideloaded record can be found in a root key named after the plural name of the belongs-to inverse resource. It’s recommended to sideload records instead of embedding, to avoid duplication (each belongs-to record is only included in the response once).

When embedding belongs-to relationships, the name of the key is the singular name of the resource, for example contact – and it contains all the record’s properties.

When sideloading has-many relationships, all the child IDs are included as an array of strings in the parent record, in a key named after the relationship’s name (not the inverse resource), suffixed with Ids.

When embedding has-many relationships, all the full child records are included as an array of hashes in the parent record, in a key named after the relationship’s name (not the inverse resource).

Saving embedded records

Some resources supports saving child records embedded. An example is invoices. A POST /v2/invoices‘s request body could look like this:

{
  "invoice": {
    "invoiceNo": 41,
    ...
    "lines:" [
      {
        "productId": "...",
        "unitPrice": 100,
        ...
      }
    ]
  }
}

It’s advantageous to embed records when possible, as you get fewer round trips to the API, and everything happens as an atomic transaction (either all or no records are saved).

Paging

You can limit long lists of resources using the paging URL params.

To use pages, you can use page and pageSize. For example, to get the second page containing 20 records per page, you would request GET /v2/invoices?page=2&pageSize=20.

pageSize cannot be greater than 1000 (which is also the default if pageSize is omitted).

Whether your results are truncated/paged can be found in the meta.paging key in the response. It will look something like:

{
  "meta": {
    "paging": {
      "page": 4,
      "pageCount": 9,
      "pageSize": 20,
      "total": 192,
      "firstUrl": "https://api.billyapp.com/v2/invoices?pageSize=20",
      "previousUrl": "https://api.billyapp.com/v2/invoices?page=3&pageSize=20",
      "nextUrl": "https://api.billyapp.com/v2/invoices?page=5&pageSize=20",
      "lastUrl": "https://api.billyapp.com/v2/invoices?page=9&pageSize=20"
    }
  },
  "invoices": [...]
}

Filtering

When listing most resources, you can filter the results by various properties.

Sorting

When listing most resources, you can sort the results using the sortProperty and sortDirection URL params. Each resource only allows sorting by specific properties. Those properties are noted in each resource’s documentation. The sortDirection must be either ASC (default) or DESC.

Code examples

PHP

<?php

//Define a reusable class for sending requests to the Billy API
class BillyClient {
    private $accessToken;

    public function __construct($accessToken) {
        $this->accessToken = $accessToken;
    }

    public function request($method, $url, $body = null) {
        $headers = array("X-Access-Token: " . $this->accessToken);
        $c = curl_init("https://api.billyapp.com/v2" . $url);
        curl_setopt($c, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
        if ($body) {
            curl_setopt($c, CURLOPT_POSTFIELDS, json_encode($body));
            $headers[] = "Content-Type: application/json";
        }
        curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
        $res = curl_exec($c);
        $body = json_decode($res);
        $info = curl_getinfo($c);
        return (object)array(
            'status' => $info['http_code'],
            'body' => $body
        );
    }
}

$client = new BillyClient("INSERT ACCESS TOKEN HERE");

//Get organization
$res = $client->request("GET", "/organization");
if ($res->status !== 200) {
    echo "Something went wrong:\n\n";
    print_r($res->body);
    exit;
}
$organizationId = $res->body->organization->id;

//Create a contact
$res = $client->request("POST", "/contacts", array(
    'contact' => array(
        'organizationId' => $organizationId,
        'name' => "Arnold",
        'countryId' => "DK"
    )
));
if ($res->status !== 200) {
    echo "Something went wrong:\n\n";
    print_r($res->body);
    exit;
}
$contactId = $res->body->contacts[0]->id;

//Get the contact again
$res = $client->request("GET", "/contacts/" . $contactId);
print_r($res->body);

Node.js

First run npm install async request.

var async = require('async'),
    request = require('request');

var accessToken = 'INSERT ACCESS TOKEN HERE';

//Define a reusable function to send requests to the Billy API
var billyRequest = function(method, url, body, callback) {
    body = body || {}
    request({
        url: 'https://api.billyapp.com/v2' + url,
        method: method,
        headers: {
            'X-Access-Token': accessToken,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(body)
    }, function(err, res, body) {
        if (err) {
            callback(err);
        } else {
            callback(null, {
                status: res.statusCode,
                body: JSON.parse(body)
            });
        }
    });
};

var organizationId, contactId;

async.series([
    function(callback) {
        //Get organization
        billyRequest('GET', '/user/organizations', {}, function(err, res) {
            if (err) {
                callback(err);
            } else if (res.status !== 200) {
                console.log('Something went wrong:');
                console.log(res.body);
                process.exit();
            } else {
                organizationId = res.body.organizations[0].id;
                callback();
            }
        });
    },
    function(callback) {
      //Create a contact
        billyRequest('POST', '/contacts', {
            contact: {
                organizationId: organizationId,
                name: 'Arnold',
                countryId: 'DK'
            }
        }, function(err, res) {
            if (err) {
                callback(err);
            } else if (res.status !== 200) {
                console.log('Something went wrong:');
                console.log(res.body);
                process.exit();
            } else {
                contactId = res.body.contacts[0].id;
                callback();
            }
        });
    },
    function(callback) {
      //Get the contact
        billyRequest('GET', '/contacts/' + contactId, {}, function(err, res) {
            if (err) {
                callback(err);
            } else if (res.status !== 200) {
                console.log('Something went wrong:');
                console.log(res.body);
                process.exit();
            } else {
                console.log(res.body);
                callback();
            }
        });
    }
], function(err) {
    if (err) {
        console.log(err);
    }
    process.exit();
});

Use case examples

Posting a payment for an invoice

When you want to mark an invoice as paid, you have to create a bank payment which matches the invoice’s amount. Let’s say you’ve just created an invoice with ID inv-1234, with a total amount due of $1,200. This is how you would create the payment:

POST https://api.billyapp.com/v2/bankPayments

{
    "bankPayment": {
        "organizationId": "YOUR COMPANY ID",
        "entryDate": "2014-01-16",
        "cashAmount": 1200,
        "cashSide": "debit",
        "cashAccountId": "BANK ACCOUNT ID",
        "associations": [
            {
                "subjectReference": "invoice:inv-1234"
            }
        ]
    }
}

cashAccountId is the account that an amount of cashAmount was deposited to/withdrawn from. cashSide: "debit" means a deposit (used for invoices). cashSide: "credit" means a withdrawal (used for bills).

Each item in the associations array is a balance modifier. Since payments can pay different types of models (invoices, bills, etc.), you add the invoice to the payment by using a “reference,” which is a type concatenated with a colon, concatenated with an ID; for example, invoice:inv-1234.

The payment’s currency is determined by the associations. This means that all associations must point to subjects in the same currency. That is, you can’t pay a USD invoice together with an EUR invoice. This currency is called subjectCurrency, if you GET the bank payment later from the API. If the subjectCurrency is different from the currency of cashAccount, you also need to set a cashExchangeRate. In this example, we assume that the cashAccount is in USD.

After this call, our example invoice (for $1,200) will be paid, which will be visible through the invoice’s isPaid property – which will be true – and its balance property, which will be 0.0.

The organizationId is only necessary if you are using an access token that’s tied to a user (rather than a company), or if you are using Basic Auth. You can list your user’s companies through GET /v2/user/organizations.

Posting a product with default price(s)

When POSTing to /v2/products, you can embed product prices this way:

POST https://api.billyapp.com/v2/products

{
    "product": {
        "organizationId": "YOUR ORGANIZATION ID",
        "name": "Bat capes",
        "accountId": "REVENUE ACCOUNT ID",
        "salesTaxRulesetId": "SALES TAX RULESET ID"
        "prices": [
            {
                "unitPrice": 14000,
                "currencyId": "USD"
            },
            {
                "unitPrice": 10000,
                "currencyId": "EUR"
            }
        ]
    }
}

The organizationId is only necessary if you are using an access token that’s tied to a user (rather than a company), or if you are using Basic Auth. You can list your user’s companies through GET /v2/user/organizations.

Resource Documentation

Following is an extensive list of resources you can interact with.

In addition to the standard resources, there are also a number of “special” routes by which you can interact with the resources – for example, sending an invoice as email. These are not yet documented.

Table of Contents

• accountGroups
• accountNatures
• accounts
• attachments
• balanceModifiers
• bankLineMatches
• bankLines
• bankLineSubjectAssociations
• bankPayments
• billLines
• bills
• cities
• commentAssociations
• comments
• contactBalancePayments
• contactBalancePostings
• contactPersons
• contacts
• countryGroups
• countries
• currencies
• daybookBalanceAccounts
• daybooks
• daybookTransactionLines
• daybookTransactions
• files
• invoiceBankAccountMappings
• invoiceLateFees
• invoiceLines
• invoiceReminderAssociations
• invoiceReminders
• invoices
• locales
• organizationInvitations
• organizations
• organizationTemplates
• organizationUserAccesses
• postings
• productPrices
• products
• reportLayouts
• salesTaxRules
• salesTaxRulesets
• states
• taxRateDeductionComponents
• taxRates
• transactions
• users
• vatFields
• vatMetaFields
• vatReturnPayments
• vatReturns
• zipcodes

Resources

/v2/accountGroups

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/accountNatures

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/accounts

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/attachments

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/balanceModifiers

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/bankLineMatches

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/bankLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/bankLineSubjectAssociations

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/bankPayments

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/billLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/bills

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/cities

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/commentAssociations

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/comments

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/contactBalancePayments

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/contactBalancePostings

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/contactPersons

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/contacts

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/countryGroups

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/countries

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/currencies

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/daybookBalanceAccounts

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/daybooks

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/daybookTransactionLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/daybookTransactions

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/files

Supports: get by id, list, create, bulk save, bulk delete

/v2/invoiceBankAccountMappings

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/invoiceLateFees

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/invoiceLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/invoiceReminderAssociations

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/invoiceReminders

Supports: get by id, list, create, bulk save, bulk delete

/v2/invoices

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/locales

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/organizationInvitations

Supports: get by id, list, create, bulk save, delete, bulk delete

/v2/organizations

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/organizationTemplates

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/organizationUserAccesses

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/postings

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/productPrices

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/products

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/reportLayouts

Supports: get by id, list, update, bulk save, bulk delete

/v2/salesTaxRules

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/salesTaxRulesets

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/states

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/taxRateDeductionComponents

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/taxRates

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/transactions

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/users

Supports: get by id, list, update, bulk save, bulk delete

/v2/vatFields

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/vatMetaFields

Supports: get by id, list, create, update, bulk save, delete, bulk delete

/v2/vatReturnPayments

Supports: get by id, list, create, update, bulk save, bulk delete

/v2/vatReturns

Supports: get by id, list, update, bulk save, bulk delete

/v2/zipcodes

Supports: get by id, list, create, update, bulk save, bulk delete