MoneyBird API

Introduction | Contacts | Estimates | Incoming invoices | Invoice profiles | Invoices | Products | Recurring invoices | Tax rates

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:

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
403 Rate limit exceeded See for details below
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