API Documentation

The Moneybird API allows you to interact with a Moneybird account. The API is RESTful and uses JSON and XML to transport information. Use cases for interacting with a Moneybird account through the API include: automate sending of invoices from your webshop or backend, synchronise contact information or import products.

This API documentation will get you started with your first requests with our API. Make sure to read our main page completely to know all aspects of our API.

Developer Account

It is possible to request a special developer account. This account will grant you access to all features of Moneybird, without the need to pay for a subscription. A developer account has some limitations to discourage the use in production (like a watermark in PDF files), but still allows you to fully test your integration with Moneybird.

To request a developer account, please email us at support@moneybird.nl and tell us about the application you are developing.

REST API Basics

A REST API describes the resources you can access in a clearly defined path structure. This documentation contains a reference for each resource in the API. Before you can use these resources, you need to know the basics of accessing the Moneybird REST API.

Paths

The Moneybird API resides on the following paths:

https://moneybird.com/api/:version/:administration_id/:resource_path.:format
  • The :version part of the path indicates the version of the API you want to use. At this moment version v2 is the only available version. By pointing to a specific version, we can make sure you always can expect equal behaviour from our API.
  • The :administration_id part indicates the administration you want to access. This id corresponds with the id you see in the path when you are accessing the administration via our web application.
  • The :resource_path part indicates the path of the resource you want to access. Specific paths to resources can be found in the API documentation. Examples of resource paths are: /contacts to retreive all contacts or /contacts/:id/notes to create new note for a contact.
  • The :format part indicates the format in which you want to transport data. Currently two formats are supported: json and xml.

Authentication

To interact with a Moneybird account, you need to authenticate yourself. Authentication is done by using OAuth, this is the only authentication mechanism available in the Moneybird API. To start with OAuth, you need to register your application, download the client ID and secret and exchange these ids for access tokens which you can use to access the API.

For more details about authentication, go to the Authentication page.

Requests

There are different approaches for making requests to our API. The command line tool curl is easy and fast for testing our API. When you want to integrate the API into your own software, you can choose to use a general purpose REST library or a specific library for the Moneybird API.

We will use curl in the examples in the documentation. To retreive a list of contacts from a Moneybird account, you can perform the following request:

curl -XGET -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" https://moneybird.com/api/v2/107693607045039116/contacts.json

A REST API uses HTTP methods to determine which action to perform on the resource. The Moneybird API responds to GET, POST, PATCH, PUT and DELETE methods. Updating a resource is normally done using PATCH. The Moneybird API also responds to PUT to update a resource, because this method is used by some REST client libraries.

Responses

The Moneybird API will always respond with a HTTP status code. This code informs you about the outcome of the API call. The API can return the following HTTP status codes:

200 OK Request was successful
201 Created Entity creation was successful
204 No Content Entity deletion was successful
400 Bad request Parameters for the request are missing or malformed. Body contains the errors.
401 Authorization required No authorization provided or invalid authorization information provided
402 Payment Required Account limit reached
403 Forbidden IP is blacklisted for API usage, see Throttling information
404 Not found Entity not found
405 Method Not Allowed The endpoint with this HTTP method is not available in the API
406 Not accepted The requested content type is not supported by the API
422 Unprocessable entity Saving the entity in the database failed due to validation errors. Body contains the errors.
429 Too many requests See Throttling information
500 Internal server error Something went wrong while processing the request. This is unexpected behaviour and requires Moneybird to fix the scenario.

After reading the HTTP status code, you can determine if the request body should be parsed. The body is in JSON or XML format, based on your request format. Most non-success error codes provide extra details in the body. Make sure to process this body, because they will provide valuable information while debugging.

Pagination

Endpoints returning a list of entities, are paginated to prevent large responses. To control the pagination, you can use the page and per_page parameters. page determines which page to return (default: 1), per_page controls the amount of entities to return (default: 50, maximum: 100)

Each paginated response contains a Link header with information about the previous and next page:

Link: <https://moneybird.com/api/v2/contacts.json?page=3>; rel="next",
    <https://moneybird.com/api/v2/contacts.json?page=1>; rel="prev"

Throttling

Usage of the Moneybird API is unlimited within the subscription and permissions of the Moneybird account you are using. To prevent fraud and abuse, requests to the API are throttled. You can request the API 150 times each 5 minutes.

The API will respond with a 429 Too many requests response. This response contains a header Retry-After containing the time after which a new request can be made.

Time Zones

For some API operations the time zone matters and using different time zones may result in API unsuccessful requests. There are several ways in which Moneybird determines the time zone used to process an API request.

The Time-Zone header

A Time-Zone header can be specified for each request containing a time zone from the list of tz database time zones. The request will then be processed in the provided time zone.

The administration time zone

If no Time-Zone header is provided and the API request happens within the scope of an administration, the time zone configured in the administration settings will be used when processing the API request.

UTC

If both of the above methods don't result in a time zone, the request will be processed in UTC instead.