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.
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.
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.
The Moneybird API resides on the following paths:
The :version part of the path indicates the version of the API you want to use. At this moment version
v2is 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:
/contactsto retrieve all contacts or
/contacts/:id/notesto create new note for a contact.
The :format part indicates the format in which you want to transport data. Currently two formats are supported:
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.
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, Moneybird PHP library by EmileBons, Httpful or plain cURL
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.
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.
Endpoints returning a list of entities, are paginated to prevent large responses. To control the pagination,
you can use the
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"
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-Aftercontaining the time after which a new request can be made.
RateLimit-Remainingcontaining the time remaining before a new request can be made.
RateLimit-Limitcontaining the total limit.
RateLimit-Resetcontaining the time after which a new request can be made.
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.
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
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.
If both of the above methods don't result in a time zone, the request will be processed in UTC instead.