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 info@moneybird.nl.
For Ruby-on-Rails programmers: don't forget to use ActiveResource! If you want to use the MoneyBird API with PHP, please take a look at the PHP library on GitHub.
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. You should log in with an existing
user, for which we advise you to create a seperate API user in your MoneyBird account. The
authentication is estabilished with HTTP Basic Authentication. An URL inside the API looks like:
https://api:password@company.moneybird.com.
The second option for authentication is OAuth. This technique has
the advantage that you don't need to store the user credentials in your application, because the
complete authentication is handled by OAuth. To start using OAuth, you should register your
application inside MoneyBird. Visit inside your MoneyBird account the url
/oauth_clients/new to register your application and start using OAuth.
XML is used to represent the information coming from the API. Besides XML, 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 response. To accomplish this, you should change the Accept and Content-Type headers to the following:
Accept: application/xml
Content-Type: application/xmlThe 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:
| 200 | OK | Request was successful |
| 201 | Created | Entity was created successful |
| 401 | Authorization required | No authorization information provided with request |
| 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. |
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.
The following tables contain all information about the commands you can use within the API. Currently it is only possible to access invoices, contacts, incoming invoices and recurring invoices through the API. Settings and user management will not be included in the API.
| Description | Method & URL | Input | Output | |
|---|---|---|---|---|
| Get all contacts | GET | /contacts.xml |
Contacts | |
| Get a contact | GET | /contacts/:id.xml |
Contact | |
| Create a new contact | POST | /contacts.xml |
Contact | Contact |
| Get fields for updating a contact | GET | /contacts/:id/edit.xml |
Contact | |
| Update a contact | PUT | /contacts/:id.xml |
Contact | |
| Delete a contact | DELETE | /contacts/:id.xml |
||
| Description | Method & URL | Input | Output | |
|---|---|---|---|---|
| Get all invoices | GET | /invoices.xml |
Invoices | |
| Get all invoices filtered | GET | /invoices/filter/:filter.xml |
Invoices | |
| Get all invoices filtered advanced by parameters | POST | /invoices/filter/advanced.xml |
Filter | Invoices |
| Get an invoice | GET | /invoices/:id.xml |
Invoice | |
| Create a new invoice | POST | /invoices.xml |
Invoice | Invoice |
| Update an invoice | PUT | /invoices/:id.xml |
Invoice | |
| Send an invoice | PUT | /invoices/:id/send_invoice.xml |
Invoice send information | |
| Register payment | POST | /invoices/:id/payments.xml |
Payment | Invoice |
| Delete an invoice | DELETE | /invoices/:id.xml |
||
| Description | Method & URL | Input | Output | |
|---|---|---|---|---|
| Get all recurring templates | GET | /recurring_templates.xml |
RecurringTemplates | |
| Get a recurring template | GET | /recurring_templates/:id.xml |
RecurringTemplate | |
| Create a new recurring template | POST | /recurring_templates.xml |
RecurringTemplate | RecurringTemplate |
| Update a recurring template | PUT | /recurring_templates/:id.xml |
RecurringTemplate | |
| Delete a recurring template | DELETE | /recurring_templates/:id.xml |
||
This sections contains an overview of XML types you can expect from the API.
<contacts>
<contact>...</contact>
<contact>...</contact>
</contacts><contact>
<id type="integer">...</id> Read-only
<name>...</name> Required
<contact-name>...</contact-name>
<address1>...</address1>
<address2>...</address2>
<zipcode>...</zipcode>
<city>...</city>
<country>...</country>
<email>...</email>
<phone>...</phone>
<customer-id>...</customer-id>
<tax-number>...</tax-number>
<contact-hash>...</contact-hash> Read-only
<created-at type="datetime">...</created-at> Read-only
<updated-at type="datetime">...</updated-at> Read-only
</contact><invoices>
<invoice>...</invoice>
<invoice>...</invoice>
</invoices><invoice>
<id type="integer">...</id> Read-only
<contact-id type="integer">...</contact-id> Required when using existing contact
<invoice-profile-id type="integer">...</invoice-profile-id>
<recurring-template-id type="integer">...</recurring-template-id> Read-only
<invoice-hash>...</invoice-hash> Read-only
<name>...</name> Required if contact-id is null
<contact-name>...</contact-name>
<address1>...</address1>
<address2>...</address2>
<zipcode>...</zipcode>
<city>...</city>
<country>...</country>
<invoice-id>...</invoice-id> Optional, will automatically be assigned if null
<invoice-date type="date">...</invoice-date> Optional, default today
<due-date-interval type="integer">...</due-date-interval>
<description>...</description>
<logo-location>...</logo-id> Read-only
<logo-position>(left|center|right)</logo-position> Read-only
<sender-address>...</sender-address>
<currency>(EUR|GBP|USD)</currency>
<language>(nl|en)</language>
<created-at type="datetime">...</created-at> Read-only
<updated-at type="datetime">...</updated-at> Read-only
<url>...</url> Read-only
<state>(draft|open|late|paid)</state> Read-only
<days-open>...</days-open> Read-only
<total-price-excl-tax type="float">...</total-price-excl-tax> Read-only
<total-tax type="float">...</total-tax> Read-only
<total-price-incl-tax type="float">...</total-price-incl-tax> Read-only
<total-paid type="float">...</total-paid> Read-only
<total-unpaid type="float">...</total-unpaid> Read-only
<details type="array">
<detail type="InvoiceDetail">
<id type="integer">...</id> Read-only
<amount type="decimal">...</amount> Required
<description>...</description> Required
<price type="decimal">...</price> Required
<tax type="decimal">...</tax> Required
<total-price-excl-tax type="decimal">...</total-price-excl-tax> Read-only
<total-price-incl-tax type="float">...</total-price-incl-tax> Read-only
<created-at type="datetime">...</created-at> Read-only
<updated-at type="datetime">...</updated-at> Read-only
</detail>
</details>
<payments type="array"> Read-only
<payment>...</payment>
<payment>...</payment>
</payments>
<history type="array"> Read-only
<history type="InvoiceHistory">
<id type="integer">...</id>
<invoice-id type="integer">...</invoice-id>
<action>...</action>
<description>...</description>
<user-id type="integer">...</user-id>
<created-at type="datetime">...</created-at>
<updated-at type="datetime">...</updated-at>
</history>
</history>
</invoice><invoice_payment>
<id type="integer">...</id> Read-only
<invoice-id type="integer">...</invoice-id> Required
<price type="decimal">...</price> Required
<payment-date type="date">...</payment-date> Required
<payment-method>...</payment-method> Required
<created-at type="datetime">...</created-at> Read-only
<updated-at type="datetime">...</updated-at> Read-only
</invoice_payment><invoice>
<send-method>(email|post|hand)</send-method>
<email>...</email>
<invoice-email>...</invoice-email>
</invoice><filter>
<states>(draft|open|late|paid)</states> Optional
<states>(draft|open|late|paid)</states> Optional
<from-date>YYYY-MM-DD</from-date> Required
<to-date>YYYY-MM-DD</to-date> Required
</filter><recurring_templates>
<recurring_template>...</recurring_template>
<recurring_template>...</recurring_template>
</recurring_templates><recurring-template>
<id type="integer">...</id> Read-only
<contact-id type="integer">...</contact-id> Required
<invoice-profile-id type="integer">...</invoice-profile-id> Optional
<start-date type="date">YYYY-MM-DD</start-date> Required
<next-date type="date">YYYY-MM-DD</next-date> Read-only
<frequency type="integer">(1|2|3|4|5|<blank>)</frequency>
<frequency-type type="integer">...</frequency-type> Required if frequency-type blank, number of days in integer
<occurences type="integer">...</occurences> Optional
<send-invoice type="boolean">...</send-invoice>
<currency>(EUR|USD|...)</currency> Optional
<active type="boolean">true</active> Read-only
<last-date type="date">...</last-date> Read-only
<template-id type="integer">...</template-id> Read-only
<total-price-excl-tax type="float">...</total-price-excl-tax> Read-only
<total-tax type="float">...</total-tax> Read-only
<total-price-incl-tax type="float">...</total-price-incl-tax> Read-only
<created-at type="datetime">2010-01-11T15:44:37+01:00</created-at> Read-only
<updated-at type="datetime">2010-01-11T15:44:37+01:00</updated-at> Read-only
<details type="array">
<detail type="RecurringTemplateDetail">
<id type="integer">...</id> Read-only
<amount>...</amount>
<description>...</description> Required
<price type="decimal">...</price>
<tax type="decimal">...</tax>
<total-price-excl-tax type="float">...</total-price-excl-tax> Read-only
<total-tax type="float">...</total-tax> Read-only
<total-price-incl-tax type="float">...</total-price-incl-tax> Read-only
</detail>
</details>
</recurring-template>