MoneyBird API Introduction

The API of MoneyBird enables you to access the information inside a MoneyBird account. The API is RESTfull and uses XML for the data representation. On this page you can find all information about the API.

Don't hesitate to contact us with your questions on support@moneybird.nl. We strongly prefer to answer specific api questions via e-mail and kindly ask you not to call us. We answer most questions within a short timeframe during office hours.

Libraries & extensions

There are several libraries available to access the MoneyBird API in different programming languages:

Please note Although we love to give you support on our API, we are not the maintainers of the libraries and extensions mentioned above. Please contact the developer with questions about the library or extension.

API accounts

Accessing the MoneyBird API is possible with every registrered MoneyBird account. It is possible to request a special developer account to access all features of MoneyBird, without the need to pay for your subscription. Please e-mail information about the integration your are building to support@moneybird.nl. A developer account is a special account that has some limitations to discourage the use in production (like a watermark in the PDF files), but still allows you to fully test your integration with MoneyBird.

Authentication

To connect to the MoneyBird API, you always use the subdomain of the MoneyBird account you want to access, for example https://company.moneybird.com. Make sure you always use https! If you use http, your request will be redirected (302 http status code) to the https location. There are two authorization methods for accessing information inside a MoneyBird account:

HTTP Basic Authentication
You should log in with an existing user, for which we advise you to create a seperate API user in your MoneyBird account. The authencation is estabilished with HTTP Basic Authentication. An URL inside the API looks like: https://api:password@company.moneybird.com.
OAuth
This technique has the advantage that you don't need to store the user credentials in your application, because the complete authentication is handled by OAuth. OAuth is mandatory for applications allowing many users to access the API. To start using OAuth, you should register your application inside MoneyBird. Inside your MoneyBird account, visit the url /oauth_clients/new to register your application and start using OAuth.

When authentication is successful, it is possible to request information about the current session and the active user by requesting /api/v1.0/current_session.xml.

Requests

XML or JSON is used to represent the information coming from the API. Besides XML and JSON, you will receive HTTP response codes with information about your request. To start using the API, you should make clear to the API you are expecting an XML or JSON response. To accomplish this, you should change the Accept and Content-Type headers to the following:

To use XML:

Accept: application/xml
Content-Type: application/xml

To use JSON:

Accept: application/json
Content-Type: application/json

The MoneyBird API uses HTTP Response Codes to inform you about the success or failure of your request. The following response status codes can be expected:

Table 1. Response status codes
200	OK	Request was successful
201	Created	Entity was created successful
401	Authorization required	No authorization information provided with request
404	Not found	The entity or action is not found in the API
406	Not accepted	The action you are trying to perform is not available in the API
422	Unprocessable entity	Entity was not created or updated because of errors in parameters. Errors are included in XML response.
500	Internal server error	Something went wrong while processing the request. MoneyBird is notified of the error.
501	Method not implemented	The action you are trying to perform is not available in the API

When the API returns a 422 Unprocessable entity error, the response will contain more information about the attributes that are invalid. Each error contains information about the attribute the error is related to and the error message.


<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>
    <attribute>details</attribute>
    <message>Details should contain at least one line</message>
  </error>
</errors>

Rate limits

In order to provide our web users with the best service, we limit the number of API requests to our services to 350 requests/hour. Please make sure your implementation respects these limits. The X-RateLimit-Limit and X-RateLimit-Remaining HTTP response headers contain information about the limit you are bound to. When you exceed the limit you will receive a 403 HTTP response code.

Examples

There are several examples available to give you an idea about the power of the MoneyBird API.

ActiveResource examples (Ruby): Import contacts from CSV, Create invoice, Find contact by customer id.

Examples of the MoneyBird PHP API can be found on the Github wiki page.

Push API

In some cases it can be necessary to store information about invoices in MoneyBird in your own database. To allow easy synchronisation of the information in your database, it is possible to receive a HTTP push when the state of an invoice is changed in MoneyBird. The HTTP push is a regular HTTP POST request and contains the id of the invoice and the new state of the invoice. To enable push messages in a MoneyBird account, please contact us!

If you want to test a push message, the following CURL call simulates a push from the MoneyBird servers:

curl -X POST -d "invoice_id=1&state=paid" -H "MoneyBird (Push API)" http://yourwebsite.com/script_for_push.php

MoneyBird API