Accessing the API

The MoneyBird class provides a low level of abstraction for communicating with the MoneyBird API. This means that the library only provides ways to minimize repetitive work, but does not contain an internal data representation of the MoneyBird data.

API docs

Knowledge of the MoneyBird API is expected and required for working with this library. API documentation can be fount at http://developer.moneybird.com/.

Set up

Before querying the API, it has to be set up properly. Every instance of the API requires a valid form of authentication:

from moneybird import MoneyBird, TokenAuthentication

moneybird = MoneyBird(TokenAuthentication('token'))

See usage/authentication for details on authentication.

Queries

For queries, there are four methods, one for each type:

Method signatures

The method signatures of these methods are pretty similar.

For all methods, the first argument is the resource url, as given by the MoneyBird API documentation, excluding the domain, version, format, etc. So for the list of contacts this will be contacts, for a specific contact this will be contacts/%(id)s.

For the post and patch methods, which send data, the second argument is the data that is to be sent. The data should be regular Python objects ready for JSON serializing. Dictionaries and lists are commonly used. The data should be formatted according to the appropriate format for the resource.

The last argument, with the keyword administration_id, should contain the administration id when this is required for the used resource.

The methods always return the response from the API or throw an exception. The response will be a Python object built from the JSON response.

The methods are described in detail below.

Example

from moneybird import MoneyBird, TokenAuthentication

# API client
moneybird = MoneyBird(TokenAuthentication('token'))

# Get an administration id
administrations = moneybird.get('administrations')

# Get all contacts for all administrations
for administration in administrations:
    id = administration['id']
    contacts = moneybird.get('contacts', administration_id=id)

    # Print invoices per contact
    for contact in contacts:
        print(contact['company_name'])

        for invoice in moneybird.get('sales_invoices?filter=contact_id:%s' % contact['id'], administration_id=id)
            print('  ', invoice['invoice_id'])

Internal API

class moneybird.api.MoneyBird(authentication: moneybird.authentication.Authentication)[source]

Bases: object

Client for the MoneyBird API.

Parameters:authentication – The authentication method to use
exception APIError(response: requests.models.Response, description: str = None)[source]

Bases: Exception

Exception for cases where communication with the API went wrong.

This exception is specialized into a number of exceptions with the exact same properties.

request

Short string representation of the request (method and URL).

response

JSON decoded data of the response.

status_code

HTTP status code of the request.

MoneyBird.delete(resource_path: str, administration_id: int = None)[source]

Performs a DELETE request to the endpoint identified by the resource path. DELETE requests are usually used to (permanently) delete existing data. USE THIS METHOD WITH CAUTION.

From a client perspective, DELETE requests behave similarly to GET requests.

Parameters:
  • resource_path – The resource path
  • administration_id – The administration id (optional, depending on the resource path)
Returns:

The decoded JSON response for the request
MoneyBird.get(resource_path: str, administration_id: int = None)[source]

Performs a GET request to the endpoint identified by the resource path.

Example:
>>> from moneybird import MoneyBird, TokenAuthentication
>>> moneybird = MoneyBird(TokenAuthentication('access_token'))
>>> moneybird.get('administrations')
[{'id': 123, 'name': 'Parkietje B.V.', 'language': 'nl', ...
>>> moneybird.get('contacts/synchronization', 123)
[{'id': '143273868766741508', 'version': 1450856630}, ...
Parameters:
  • resource_path – The resource path
  • administration_id – The administration id (optional, depending on the resource path)
Returns:

The decoded JSON response for the request
MoneyBird.patch(resource_path: str, data: dict, administration_id: int = None)[source]

Performs a PATCH request to the endpoint identified by the resource path. PATCH requests are usually used to change existing data.

From a client perspective, PATCH requests behave similarly to POST requests.

Parameters:
  • resource_path – The resource path
  • data – The data to send to the server
  • administration_id – The administration id (optional, depending on the resource path)
Returns:

The decoded JSON response for the request
MoneyBird.post(resource_path: str, data: dict, administration_id: int = None)[source]

Performs a POST request to the endpoint identified by the resource path. POST requests are usually used to add new data.

Example:
>>> from moneybird import MoneyBird, TokenAuthentication
>>> moneybird = MoneyBird(TokenAuthentication('access_token'))
>>> data = {'url': 'http://www.mocky.io/v2/5185415ba171ea3a00704eed'}
>>> moneybird.post('webhooks', data, 123)
{'id': '143274315994891267', 'url': 'http://www.mocky.io/v2/5185415ba171ea3a00704eed', ...
Parameters:
  • resource_path – The resource path
  • data – The data to send to the server
  • administration_id – The administration id (optional, depending on the resource path)
Returns:

The decoded JSON response for the request
MoneyBird.renew_session()[source]

Clears all session data and starts a new session using the same settings as before.

This method can be used to clear session data, e.g., cookies. Future requests will use a new session initiated with the same settings and authentication method.