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.

Sandbox Administration

We offer special sandbox administrations to test your API integration. These administrations grant full access to all our features without the need to subscribe to our services. A sandbox account is limited for production usage, for example invoices have watermarks.

To open a sandbox administration, make sure you have a Moneybird user account by registering on our website. If you already have an account, there is no need to register again. Once our are logged in, visit the sandbox creation page to create a sandbox.

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 retrieve 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.

Id's

Each resource in Moneybird has an unique id. These id's are large integers. Some JSON parsing tools may have trouble with these large integers. To prevent problems, we recommend to parse the id's as strings.

Authentication

To interact with a Moneybird account through the API, you need to authenticate yourself. Authentication can be done through OAuth or by using a personal API token.

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.

• Ruby: REST Client, ActiveResource or Moneybird Ruby client by Maarten van Vliet
• PHP: Moneybird PHP client by Picqer, Httpful or plain cURL
• JS: Moneybird JS client by Print.one

We will use curl in the examples in the documentation. To retrieve 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.

Please note that our API requests are cached for performance optimization. As a result, we strongly advise against using GET methods for verification purposes as this may result in an incomplete result. To verify API requests, developers can check the response status codes returned by the API.

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:

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 the following fields in the headers:

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.