Documentation

Welcome to Moneybird

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.

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:

Code
 
https://moneybird.com/api/:version/:administration_id/:resource_path.:format

• The 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 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 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 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:

Code
 
    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:

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:

Code
 
    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:

Retry-After containing the time after which a new request can be made.

RateLimit-Remaining containing the time remaining before a new request can be made.

RateLimit-Limit containing the total limit.

RateLimit-Reset 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.