# 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:
[sending of invoices](api/sales-invoices#sends-an-invoice)
automatically from your webshop or backend,
[synchronising contact information](api/contacts#get-contact-by-customer-id)
or [importing products](api/products#list-all-products-of-an-administration).

This API documentation will get you started with your first requests with
our API. Make sure to read this guide 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. Sandbox accounts have limitations for
production use: 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 you are logged in, [visit the
sandbox creation
page](https://moneybird.com/administrations/sandboxes/new) to create a
sandbox.

## REST API Basics

A <abbr title="REpresentational State Transfer">REST</abbr>
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 path:

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

## IDs

Each resource in Moneybird has an unique ID. These IDs are large
integers. Some JSON parsing tools may have trouble with these large
integers. To prevent problems, we recommend to parse the IDs 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](/authentication) page.

## Requests

There are different approaches for making requests to our API. The
command line tool [curl](http://curl.haxx.se/) 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](https://github.com/rest-client/rest-client),
  [ActiveResource](https://github.com/rails/activeresource) or
  [Moneybird Ruby client by Maarten van
  Vliet](https://github.com/maartenvanvliet/moneybird)
- **PHP**: [Moneybird PHP client by
  Picqer](https://github.com/picqer/moneybird-php-client),
  [Httpful](https://github.com/nategood/httpful) or [plain
  cURL](/php-with-curl)
- **JS**: [Moneybird JS client by
  Print.one](https://github.com/print-one/moneybird-js)

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:

```bash
    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 an 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](#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](#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:

```http
    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 on a per ip-address basis. You can request the API 150
times each 5 minutes, with a stricter limit of 50 requests per 5 minutes
for all the `/reports/` endpoints.

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.

Partners with popular Oauth Applications can request a per-administration limit 
instead of ip-address limits. We can also make special volume based price agreements
for accounts that consistently hit our rate limits due to their volumes. For both cases, 
please contact our support team.

## 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](https://en.wikipedia.org/wiki/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.