How to Integrate the Moneybird API in Your Application

The Moneybird API is a REST interface that gives your application read and write access to every resource inside a Moneybird administration - contacts, sales invoices, products, payments, bank transactions, and more. It speaks JSON (and optionally XML), authenticates over HTTPS using OAuth 2.0 or a personal access token, and organizes every resource under a predictable URL structure rooted at https://moneybird.com/api/v2/.
If you want to automate invoicing, synchronize contacts, reconcile bank feeds, or trigger accounting workflows from your own product, this guide walks you through the entire path - from your first token to a production-grade integration. It adds what a reference can't: end-to-end workflow examples, webhook handler design, error handling, and a production readiness checklist.
This guide was checked against Moneybird's public documentation and OpenAPI specification in October 2026. Code examples are illustrative starting points; review them against your own security requirements before deploying to production.
What the Moneybird API can do for your application
Moneybird is a Dutch SaaS accounting platform, widely used by freelancers, small businesses, and growing companies across the Netherlands. Its API gives your application full programmatic control over an administration's financial data.
Common use cases include:
- Invoicing automation - create, send, and monitor sales invoices without manual data entry.
- Contact synchronization - keep your CRM aligned with Moneybird's contact records so customer data lives in one place.
- Bank reconciliation - import bank statements and link financial mutations to invoices automatically.
- Financial reporting - pull profit and loss, balance sheet, and tax reports for dashboards or ERP exports.
- Product catalog management - maintain a shared product and pricing catalog that feeds both your storefront and your invoices.
Supported resource types at a glance
The API organizes data into resource groups. The table below maps each group to its primary purpose and the HTTP methods it supports:
| Resource group | Primary purpose | Typical HTTP methods |
|---|---|---|
| Contacts | Customer and supplier records | GET, POST, PATCH, DELETE |
| Sales invoices | Client invoicing and payment tracking | GET, POST, PATCH, DELETE, plus PATCH send_invoice |
| Purchase invoices | Supplier bill management | GET, POST, PATCH, DELETE |
| Products | Reusable line-item catalog | GET, POST, PATCH, DELETE |
| Financial accounts | Bank and cash account definitions | GET |
| Financial statements | Bank statement imports | POST, PATCH, DELETE |
| Financial mutations | Individual bank transaction lines | GET, plus PATCH link_booking and DELETE unlink_booking |
| Payments | Invoice payment records | GET, plus POST and DELETE under the invoice |
| Ledger accounts | Chart of accounts | GET, POST, PATCH, DELETE |
| Tax rates | VAT rate definitions | GET |
| Webhooks | Event subscription management | GET, POST, DELETE, plus PATCH activate and deactivate |
| Projects | Time and expense grouping | GET, POST, PATCH, DELETE |
| Reports | Financial overviews | GET |
Direct integration vs. a unified API layer
A unified accounting API puts many accounting platforms behind a single generic schema. That approach makes sense when you need to support multiple accounting backends from one codebase. Direct integration makes more sense when:
- You need access to Moneybird-specific fields (SEPA mutation data,
settlement_state, Dutch VAT structures) that a unified layer flattens away. - Your team can maintain a single, well-tested integration rather than a generalized abstraction.
- You want real-time webhook events from Moneybird without a polling proxy in between.
For teams that have built open banking API integrations or payment-processor connections before, direct Moneybird integration follows the same patterns and is straightforward to maintain.
Using the PHP client
If you work in PHP, moneybird-api-php is our open-source Moneybird API client (source on GitHub). Install it with Composer:
composer require sandorian/moneybird-api-php
The package is still evolving, so pin a specific version. The examples in this guide use plain HTTP so they translate to any language.
How Moneybird API authentication works
Every request to the Moneybird API must carry a valid Bearer token in the Authorization HTTP header. There are two ways to obtain one.
Personal access tokens (fastest way to get started)
A personal access token is a long-lived credential tied to a single Moneybird user account. Generate one in Moneybird:
- Log in to moneybird.com.
- Open moneybird.com/user/applications/new.
- Choose the option to create a personal API token.
- Select the scopes you need, then store the generated token in your secret manager.
Moneybird describes a personal token as similar to a password, with access to your entire company account. Use them for server-side scripts, internal tooling, or quick proof-of-concepts where multi-tenant access is not needed. Do not embed them in client-side code or mobile apps.
OAuth 2.0 for multi-tenant applications
When your application acts on behalf of multiple Moneybird users - a SaaS product, an accounting integration, a marketplace - you need OAuth 2.0 (RFC 6749). Moneybird implements the Authorization Code grant:
- Register your app. Open moneybird.com/user/applications/new and register an external application. You receive a
client_idandclient_secret. - Redirect the user. Send the user to:
https://moneybird.com/oauth/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.com/callback &response_type=code &scope=sales_invoices%20bank - Exchange the code. After the user authorizes your app, Moneybird redirects to your
redirect_uriwith acodeparameter. POST it tohttps://moneybird.com/oauth/tokenalong with yourclient_id,client_secret,redirect_uri, andgrant_type=authorization_code. - Store and refresh. The response includes an
access_tokenand arefresh_token. Access tokens currently do not expire, but Moneybird may change that. If a response includesexpires_in, use the refresh token to obtain a new access token without prompting the user again.
Choosing the right OAuth scopes
Scopes control which parts of the Moneybird API your token can reach. Requesting broader scopes than you need creates unnecessary risk. Moneybird defines six scopes, and uses sales_invoices when you provide none:
| Scope | What it grants | Typical use case |
|---|---|---|
sales_invoices |
Sales invoices, external sales invoices, their payments, and contacts | Invoicing automation |
documents |
Purchase invoices, receipts, and other documents, plus contacts | Accounts payable automation |
estimates |
Estimates and contacts | Quoting workflows |
bank |
Financial statements and mutations, plus contacts | Bank reconciliation |
time_entries |
Time entries | Time tracking |
settings |
Financial accounts, products, projects, ledger accounts, tax rates, webhooks, and contacts | Initial setup, chart of accounts sync |
Request the minimum set your integration requires. An invoicing bot needs sales_invoices; a bank reconciliation service needs bank, plus sales_invoices if it links mutations to sales invoices. Add settings only when your app genuinely needs it, for example to register webhooks.
Constructing the authorization header
Once you have a token, every API request carries:
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Here is a minimal cURL call to confirm the token works:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://moneybird.com/api/v2/administrations.json
Security checklist - token storage and rotation
- Store tokens in environment variables or a secrets manager (HashiCorp Vault, AWS Secrets Manager), never in source code or version control.
- Rotate personal access tokens on a schedule (every 90 days is a sensible baseline).
- Scope OAuth tokens to the minimum permissions the integration needs.
- Enforce HTTPS on all inbound webhook endpoints - reject any plaintext HTTP request immediately.
- Never log raw Bearer tokens in application logs.
Personal access token vs. OAuth 2.0: how to decide
| Criterion | Personal access token | OAuth 2.0 |
|---|---|---|
| Setup time | Minutes | Hours (app registration + flow) |
| Multi-user support | No - single account only | Yes - any Moneybird user |
| Token lifespan | Long-lived (until revoked) | Currently no expiry; handle expires_in if returned |
| Revocation control | Manual, in Moneybird | Programmatic via oauth/revoke |
| Best for | Internal scripts, single-tenant tools | SaaS products, marketplaces |
| Blast radius | One token for the whole company account | One scoped token per connected user |
Core concepts you need before writing any code
The administration_id - what it is and how to get it
The administration_id is the numeric identifier for a specific Moneybird financial administration. Every administration-level endpoint URL includes it directly after the API version. One Moneybird user account can belong to multiple administrations (for example, separate legal entities), so the administration_id tells the API which set of books to operate on.
Finding it in the UI: After logging in, the URL in your browser reads https://moneybird.com/{administration_id}/... - the long number in that path is your administration ID.
Retrieving it programmatically: Call the Administrations endpoint:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://moneybird.com/api/v2/administrations.json
The response is an array of administration objects, each containing an id field. Pick the id that matches the administration name you want to work with, then store it alongside your token for all subsequent requests. Moneybird IDs are large integers, and the docs recommend parsing them as strings.
The API URL structure and format suffix (.json vs. .xml)
Every Moneybird API v2 endpoint follows this pattern:
https://moneybird.com/api/v2/{administration_id}/{resource}/{id}{format}
| URL segment | Example | Notes |
|---|---|---|
v2 |
v2 |
Current API version - always use v2 |
{administration_id} |
123456789012345678 |
18-digit numeric ID |
{resource} |
sales_invoices |
Plural snake_case resource name |
{id} |
987654321098765432 |
Optional - omit for collection endpoints |
{format} |
.json |
.json or .xml |
The format is part of the documented path, so always append it explicitly. XML is available, but JSON is the better default for new integrations.
API versioning and how to track changes
Version 2 is the only available version of the Moneybird REST API. Moneybird publishes changes in the official API changelog and an RSS feed. Subscribe to the feed so changes reach you before they reach production. For strategies on protecting your integration against version changes, our guide to API versioning for long-lived B2B integrations covers the patterns that work in practice.
Key endpoints and what they're for
The table below gives you an integration map at a glance. All paths are relative to https://moneybird.com/api/v2/{administration_id}/.
| Resource | Methods | Required scope | Primary use case |
|---|---|---|---|
contacts |
GET, POST, PATCH, DELETE | Any of sales_invoices, documents, estimates, bank, settings |
Create and sync customer records |
sales_invoices |
GET, POST, PATCH, DELETE | sales_invoices |
Invoice creation and status tracking |
external_sales_invoices |
GET, POST, PATCH, DELETE | sales_invoices |
Import invoices from other systems |
products |
GET, POST, PATCH, DELETE | settings |
Reusable catalog items |
financial_accounts |
GET | settings |
List bank and cash accounts |
financial_statements |
POST, PATCH, DELETE | bank |
Bank statement imports |
financial_mutations |
GET | bank |
Individual transaction lines |
financial_mutations/{id}/link_booking |
PATCH | bank, plus the scope of what you link |
Process a transaction |
sales_invoices/{id}/payments |
POST | sales_invoices |
Record invoice payments |
ledger_accounts |
GET, POST, PATCH, DELETE | settings to write |
Chart of accounts management |
tax_rates |
GET | Any of settings, sales_invoices, documents, estimates |
VAT rate definitions |
webhooks |
GET, POST, DELETE | settings |
Event subscriptions |
projects |
GET, POST, PATCH, DELETE | settings |
Project grouping for invoices |
Contacts
The Contacts resource stores customers, suppliers, and any other party your administration transacts with. To find an existing contact before creating a duplicate, use the query filter parameter:
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://moneybird.com/api/v2/{admin_id}/contacts.json?query=acme"
Creating a contact requires at minimum a company_name or firstname/lastname. The response includes an id that you store and use as contact_id on subsequent invoice objects.
Sales invoices and external sales invoices
Sales invoices are the core of most Moneybird integrations. Creating one requires a contact_id. Optional fields include reference, invoice_date, first_due_interval, and an array of details_attributes (line items). A line item can set description, price, amount, tax_rate_id, ledger_account_id, and product_id.
For invoices that originate in another system - a POS, an e-commerce platform - use the external_sales_invoices endpoint instead. It signals to Moneybird that the source of truth lives outside.
Products
The Products resource stores reusable catalog items with fixed pricing, tax rates, and ledger account assignments. Reference one with product_id on a sales invoice line item to keep your invoices consistent with the catalog.
Financial accounts, statements, and mutations
These three resources form a hierarchy. A financial account represents a bank or cash account (for example, an ING business account). A financial statement represents an imported bank statement - a batch of transactions for a date range. Financial mutations are the individual transaction lines within a statement; each one has an amount, date, message, and SEPA fields like contra_account_number and batch_reference.
A financial mutation starts with state set to unprocessed. Linking it to an invoice or ledger account through link_booking processes it. Only mutations with a settlement_state of settled, authorised, or pending can be linked. Automating this matching pipeline is one of the highest-value use cases for the Moneybird API.
Payments
A payment records that money was received against an invoice. You create it on the invoice itself: POST to sales_invoices/{id}/payments with at least payment_date and price. Moneybird will update the invoice's payment status accordingly and, if the amount matches, mark it as fully paid.
Webhooks
Webhooks let Moneybird push events to your server instead of your app polling for changes. The next section covers webhook setup in full.
Reports
The Reports endpoints return aggregated financial data - profit and loss, tax, balance sheets. Most are read-only GET requests, and they have a stricter rate limit than the rest of the API.
Working with Moneybird API pagination
How Moneybird paginates results
The Moneybird REST API returns paginated responses for collection endpoints. Two query parameters control pagination:
page- the page number, starting at1.per_page- records per page, default50, maximum100.
Each paginated response includes a Link header with rel="next" and rel="prev" URLs, so you can follow rel="next" until it disappears. The examples below use a simpler check: a page with fewer records than per_page is the last one.
Not every list endpoint paginates. Financial mutations, for example, take a filter but no page parameter, and offer synchronization endpoints for fetching larger sets. If you work in PHP, the pagination guide for moneybird-api-php lists which endpoints behave which way.
Iterating all pages in PHP
<?php
function fetchAllContacts(string $adminId, string $token): array {
$allContacts = [];
$page = 1;
$perPage = 100;
do {
$url = "https://moneybird.com/api/v2/{$adminId}/contacts.json"
. "?page={$page}&per_page={$perPage}";
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer {$token}",
"Content-Type: application/json",
],
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
throw new RuntimeException("API error: HTTP {$httpCode}");
}
$batch = json_decode($response, true);
$allContacts = array_merge($allContacts, $batch);
$page++;
} while (count($batch) === $perPage);
return $allContacts;
}
Iterating all pages in Python
The moneybird-python library wraps some of this boilerplate, but here is the raw approach using requests for teams that prefer minimal dependencies:
import requests
def fetch_all_contacts(admin_id: str, token: str) -> list:
all_contacts = []
page = 1
per_page = 100
base_url = f"https://moneybird.com/api/v2/{admin_id}/contacts.json"
headers = {"Authorization": f"Bearer {token}"}
while True:
response = requests.get(
base_url,
headers=headers,
params={"page": page, "per_page": per_page},
timeout=10,
)
response.raise_for_status()
batch = response.json()
all_contacts.extend(batch)
if len(batch) < per_page:
break
page += 1
return all_contacts
Performance tips for large datasets
- Use the
filterparameter where it exists to sync only recent records - for examplecontacts/filter.json?filter=updated_after:2026-10-01 00:00:00 UTC- rather than fetching all pages on every run. - Use
synchronizationendpoints where they exist. They return record IDs and versions, so you only fetch what changed. - Avoid requesting
per_page=100when you only need a few records - smaller pages reduce latency on endpoints that serialize large JSON objects.
A real-world integration workflow
This section shows the complete sequence that most invoicing integrations need to execute: discover the administration, find or create a contact, build a sales invoice, find the matching bank transaction, and link the two.
The data flows like this:
Administration → Contact → Sales invoice (with line items linked to Products and Tax Rates) → Financial mutation (from the bank feed) → Linked booking
Step 1 - Discover your administration ID
$adminList = apiGet('/api/v2/administrations.json', $token);
$adminId = $adminList[0]['id']; // Pick the correct administration by name
Step 2 - Create or find a contact
function findOrCreateContact(string $adminId, string $token, array $contactData): string {
// Search first to avoid duplicates
$search = apiGet("/api/v2/{$adminId}/contacts.json?query=" . urlencode($contactData['company_name']), $token);
if (!empty($search)) {
return $search[0]['id'];
}
$contact = apiPost("/api/v2/{$adminId}/contacts.json", $token, ['contact' => $contactData]);
return $contact['id'];
}
Step 3 - Create a sales invoice with line items
$invoicePayload = [
'sales_invoice' => [
'contact_id' => $contactId,
'invoice_date' => date('Y-m-d'),
'first_due_interval' => 30,
'reference' => 'INV-2026-001',
'details_attributes' => [
[
'description' => 'API integration consulting',
'price' => '1500.00',
'amount' => '1',
'tax_rate_id' => $taxRateId, // Fetch from /tax_rates.json
'ledger_account_id'=> $ledgerAccountId, // Fetch from /ledger_accounts.json
],
],
],
];
$invoice = apiPost("/api/v2/{$adminId}/sales_invoices.json", $token, $invoicePayload);
$invoiceId = $invoice['id'];
In my experience, the most common source of 422 errors on invoice creation is a missing or invalid tax_rate_id. Always fetch and cache the available tax rates at startup rather than hard-coding IDs that may differ between administrations.
Step 4 - Find the bank transaction
Once the bank statement arrives (either via the UI or a bank feed), look for unprocessed mutations:
$filter = urlencode('period:this_month,state:unprocessed');
$mutations = apiGet("/api/v2/{$adminId}/financial_mutations.json?filter={$filter}", $token);
Match on amount, reference, or contra_account_number, depending on what your customers put in their payment description.
Step 5 - Link the mutation to the invoice
$linkPayload = [
'booking_type' => 'SalesInvoice',
'booking_id' => $invoiceId,
'price_base' => '1815.00', // Including VAT
];
apiPatch("/api/v2/{$adminId}/financial_mutations/{$mutationId}/link_booking.json", $token, $linkPayload);
The response returns the mutation with its payments and ledger_account_bookings, so you can confirm the link.
For money that never appears on a bank feed, register the payment on the invoice instead:
$paymentPayload = [
'payment' => [
'payment_date' => date('Y-m-d'),
'price' => '1815.00', // Including VAT
],
];
apiPost("/api/v2/{$adminId}/sales_invoices/{$invoiceId}/payments.json", $token, $paymentPayload);
Use one route or the other for the same money, never both.
The full helper functions (apiGet, apiPost, apiPatch) follow the same pattern: set the Bearer header, encode the body as JSON, handle the HTTP status code, and decode the response. The error handling section below shows how to make them resilient.
Setting up and handling Moneybird API webhooks
Registering a webhook endpoint
POST to the Webhooks resource to register your listener URL. Moneybird checks that the URL responds with a 200 when you register it:
curl -X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/hooks/moneybird",
"enabled_events": ["sales_invoice_created", "sales_invoice_state_changed_to_paid", "contact_changed"]
}' \
"https://moneybird.com/api/v2/{admin_id}/webhooks.json"
The older events parameter has been removed, and requests that use it are rejected. The response includes a secret field - this is the signing secret for webhook payloads, and the only time the API exposes it. Store it securely alongside your API token. If you lose it, you can reveal or rotate it on the webhook's page in Moneybird.
Available webhook events
Moneybird triggers webhooks for changes across its major resources. Common events include:
sales_invoice_created,sales_invoice_updated,sales_invoice_destroyedsales_invoice_state_changed_to_paid,sales_invoice_state_changed_to_lateexternal_sales_invoice_created,external_sales_invoice_updated,external_sales_invoice_destroyedcontact_created,contact_changed,contact_destroyedpayment_registered,payment_destroyed,payment_linked_to_financial_mutationfinancial_statement_created,financial_statement_updated,financial_statement_destroyed
Check the webhook events reference for the complete and current list. Always set enabled_events: without it, a webhook falls back to the old behaviour and only notifies you of sales invoice state changes.
Verifying the webhook payload
Moneybird signs each webhook request with a Moneybird-Signature header, for example t=1748534400,v1=5257a869.... The v1 value is an HMAC-SHA256 digest of the timestamp, a literal ., and the raw request body, keyed with your signing secret. During a secret rotation the header carries one v1 value per active secret, so accept the request if any of them matches.
function verifyMoneybirdSignature(string $rawBody, string $header, string $secret): bool {
$timestamp = null;
$signatures = [];
foreach (explode(',', $header) as $part) {
[$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
if ($key === 't') {
$timestamp = $value;
} elseif ($key === 'v1') {
$signatures[] = $value;
}
}
if ($timestamp === null || abs(time() - (int) $timestamp) > 300) {
return false; // Missing or stale timestamp
}
$expected = hash_hmac('sha256', "{$timestamp}.{$rawBody}", $secret);
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return true;
}
}
return false;
}
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_MONEYBIRD_SIGNATURE'] ?? '';
if (!verifyMoneybirdSignature($rawBody, $header, getenv('MONEYBIRD_WEBHOOK_SECRET'))) {
http_response_code(401);
exit('Unauthorized');
}
Verify against the exact bytes you received. Parsing and re-encoding the JSON changes them and breaks the signature. Use hash_equals rather than === to prevent timing attacks.
Designing an idempotent webhook handler
When your endpoint answers with anything other than a 200, Moneybird retries the push up to 10 times, at growing intervals. Duplicate delivery is normal, not exceptional. Your handler must be idempotent: processing the same push twice must produce the same result as processing it once.
Every push carries an Idempotency-Key header, which is unique to that push. Store it in a database table the first time you process it, and skip processing if the key already exists. The payload itself has entity_type, entity_id, state, action, and the full record in entity.
function handleWebhook(array $payload, string $idempotencyKey): void {
if (WebhookLog::alreadyProcessed($idempotencyKey)) {
http_response_code(200); // Acknowledge without reprocessing
return;
}
// Process the event
match ($payload['action']) {
'contact_created' => ContactSync::create($payload['entity']),
'sales_invoice_created' => InvoiceSync::create($payload['entity']),
'sales_invoice_state_changed_to_paid' => InvoiceSync::markPaid($payload['entity']),
default => null,
};
WebhookLog::markProcessed($idempotencyKey);
http_response_code(200);
}
handleWebhook(json_decode($rawBody, true), $_SERVER['HTTP_IDEMPOTENCY_KEY'] ?? '');
For a deeper look at why idempotency matters in financial contexts, our article on idempotency in API integrations covers the theoretical and practical angles. This pattern comes directly from production integrations we have built at Sandorian - the same design we apply to Mollie payment webhooks and open banking event streams. You can see how we apply it in our guide to Mollie API integration patterns.
Why idempotency matters for financial webhooks: A duplicate
payment_registeredevent that triggers a second payment record creates a false double-payment in your books. A duplicatesales_invoice_createdevent that creates a second invoice charges your customer twice. The cost of getting this wrong is not a minor bug - it is a financial error that requires manual reconciliation to undo.
Moneybird API error handling and rate limits
HTTP status codes the API returns
The Moneybird REST API uses standard HTTP status codes as defined in RFC 7231. Here is the complete reference for codes you will encounter in practice:
| Code | Meaning | Common cause | Recommended action |
|---|---|---|---|
200 OK |
Request succeeded | Successful GET or PATCH | Parse and use the response body |
201 Created |
Resource created | Successful POST | Read the id from the response |
204 No Content |
Resource deleted | Successful DELETE | No body to parse |
400 Bad Request |
Parameters missing or malformed | Invalid request body | Read the errors in the response body |
401 Unauthorized |
Authentication failed | Missing or invalid token | Check the token; refresh it if it has expired |
402 Payment Required |
Account limit reached | The Moneybird account has hit a limit | Check the account's plan and limits |
403 Forbidden |
IP blacklisted for API usage | See the rate limits below | Stop retrying and contact Moneybird |
404 Not Found |
Resource does not exist | Wrong ID or administration_id | Check IDs; log the request URL for debugging |
405 Method Not Allowed |
Method not available | Endpoint does not support this HTTP method | Check the endpoint in the API reference |
406 Not Acceptable |
Content type not supported | Unsupported format | Use .json URLs and JSON content types |
422 Unprocessable Entity |
Validation failed | Invalid field value or missing required field | Parse the error body; fix the payload |
429 Too Many Requests |
Rate limit hit | Too many requests in a short window | Back off and retry after the indicated delay |
500 Internal Server Error |
Moneybird server error | Temporary API issue | Retry with exponential backoff |
Parsing 422 validation error bodies
A 422 response includes a JSON body that names the failing fields. error is either a message or an object with a list of problems per field, and details carries the same errors as codes. Always log and surface this body during development:
{
"error": {
"firstname": ["is required"],
"company_name": ["is required"]
},
"details": {
"firstname": [{ "error": "is required" }],
"company_name": [{ "error": "is required" }]
}
}
In PHP:
if ($httpCode === 422) {
$errorBody = json_decode($response, true);
throw new ValidationException(json_encode($errorBody['error'] ?? 'Validation failed'));
}
The three most common 422 causes I see in Moneybird integrations:
- Missing or invalid
tax_rate_idon invoice line items. contact_idpointing to a contact in a different administration.- Date fields sent in the wrong format (use
Y-m-d, not timestamps).
Rate limits and retry strategy
Moneybird's API docs set the limit per IP address: 150 requests every 5 minutes, and a stricter 50 requests every 5 minutes for all /reports/ endpoints. Above that, the API returns 429 Too Many Requests with Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Always read these headers rather than guessing a delay. Partners with popular OAuth applications can ask Moneybird for a per-administration limit instead.
For integrations that push large batches - bulk contact sync, mass invoice creation - plan on one request every 2 seconds at most, which is what 150 requests per 5 minutes allows when sustained.
Exponential backoff implementation
For transient errors (429, 500, 503), retry with exponential backoff and jitter rather than retrying immediately:
function apiRequestWithRetry(string $url, string $token, int $maxRetries = 5): array {
$attempt = 0;
while ($attempt < $maxRetries) {
[$httpCode, $body] = makeApiRequest($url, $token);
if ($httpCode === 200 || $httpCode === 201) {
return json_decode($body, true);
}
if ($httpCode >= 400 && $httpCode < 500 && $httpCode !== 429) {
// Non-retryable client errors
throw new ApiException("Client error {$httpCode}: {$body}");
}
$waitSeconds = (2 ** $attempt) + (random_int(0, 1000) / 1000);
sleep((int) $waitSeconds);
$attempt++;
}
throw new ApiException("API request failed after {$maxRetries} attempts");
}
The jitter (random_int) prevents multiple concurrent workers from hitting the API simultaneously after a shared retry interval - a pattern we also apply in our Mollie API client work and any integration where fan-out retries could cause a thundering-herd problem.
Production readiness checklist
Before you ship a Moneybird integration to production, work through this checklist:

- Token storage - API tokens and OAuth secrets are in environment variables or a secrets manager, not in source code.
- Minimal scope - OAuth app requests only the scopes the integration actually uses.
- Token rotation - a process exists to rotate personal access tokens every 90 days.
- HTTPS enforcement - all webhook listener URLs use HTTPS; plaintext requests are rejected with
400. - Webhook verification - every inbound webhook's
Moneybird-Signatureis verified against the raw body before processing. - Idempotent handlers - webhook handlers store the
Idempotency-Keyand skip duplicates. - Pagination complete - all list-fetching code uses a loop or a
synchronizationendpoint and does not assume a single page is complete. - Error handling - all HTTP error codes are caught, logged, and surfaced with the full response body for
422errors. - Retry logic - transient errors (
429,500) trigger exponential backoff with jitter; other client errors are not retried. - administration_id scoped - all requests use the correct
administration_idfor the target user; multi-administration setups store the ID per-user, not globally. - Rate limit headroom - bulk operations stay under 150 requests per 5 minutes per IP address, and 50 for reports.
- Logging and observability - request/response logs (without Bearer tokens) are written to a structured log store with at least 30-day retention.
Logging and observability
Log every outbound API call with at minimum: the request URL (without the token), the HTTP method, the response code, and the response time. Log the full response body for non-2xx responses. A structured log entry lets you replay what happened when a contact failed to sync or an invoice bounced with a 422 three weeks ago.
Secret management and token rotation
Treat Moneybird tokens with the same care as database credentials. If a token leaks, revoke it in Moneybird immediately and generate a replacement. For OAuth applications, build a token refresh flow even though access tokens do not currently expire, so a future change does not cause silent integration failures - a failed refresh should alert your engineering team, not silently drop data.
Our approach to API design patterns for production applications covers secret management and circuit-breaker patterns that apply equally well to Moneybird integrations.
Handling multi-administration setups
If you are building a multi-tenant SaaS product, each of your customers may have multiple Moneybird administrations (for example, multiple legal entities). Store the administration_id at the user-administration level, not at the user level. When a user adds a new administration, re-run the administration discovery call and prompt them to select which administration your integration should operate on.
Frequently asked questions
What is the Moneybird API and what can I build with it?
The Moneybird API is a REST interface to the Moneybird Dutch accounting platform. It gives applications programmatic access to contacts, invoices, products, financial accounts, bank transactions, payments, and reports. You can build invoicing automation, contact synchronization, bank reconciliation pipelines, financial dashboards, and multi-administration accounting tools against it.
Does Moneybird have a sandbox or test environment?
Yes. Moneybird offers free sandbox administrations for testing API integrations. They have usage limits, but no subscription is needed. Run all development and integration tests in one, and never run write operations against a live production administration during development.
What is the difference between a personal access token and OAuth 2.0?
A personal access token is a long-lived credential tied to a single Moneybird user. It is fast to set up and suited for server-side scripts and internal tools, but it cannot act on behalf of other users. OAuth 2.0 is the right choice for any application that connects multiple different Moneybird accounts - it gives each user their own scoped access token, which your app can refresh without their involvement if it ever expires.
What is the administration_id, and where do I find it?
The administration_id is the 18-digit numeric identifier for a Moneybird financial administration. You can read it from the browser URL bar when logged in to Moneybird (https://moneybird.com/{administration_id}/...), or retrieve it programmatically by calling GET https://moneybird.com/api/v2/administrations.json with your Bearer token.
What OAuth scopes does the Moneybird API support?
There are six: sales_invoices (sales invoices and contacts), documents (purchase invoices and other documents), estimates, bank (financial statements and mutations), time_entries, and settings (financial accounts, products, ledger accounts, tax rates, webhooks). Request only the scopes your integration actually uses.
What is a financial mutation in Moneybird?
A financial mutation is a single transaction line within a bank statement import in Moneybird. It carries fields like amount, date, message, and payment details such as the contra account number and batch reference. Mutations start with state set to unprocessed and become processed once linked to an invoice or ledger account through link_booking. Automating this matching is one of the primary use cases for the financial accounts and statements API.
How do I handle 422 validation errors from the Moneybird API?
A 422 response body contains an error value that names which fields failed and why. Always parse and log this body. The three most common causes are: a missing or invalid tax_rate_id on invoice line items, a contact_id from a different administration, and date fields not formatted as Y-m-d. Fix the payload based on the error message and retry.
Does the Moneybird API have rate limits?
Yes. Moneybird's API docs allow 150 requests every 5 minutes per IP address, and 50 every 5 minutes for /reports/ endpoints. Above that, the API returns 429 Too Many Requests with a Retry-After header. Implement exponential backoff with jitter for all retryable error codes, and pace bulk operations at one request every 2 seconds at most.
How do I verify that a Moneybird webhook is authentic?
Moneybird sends a Moneybird-Signature header with every webhook request. It holds a timestamp and an HMAC-SHA256 digest of the timestamp and raw request body, keyed with the secret Moneybird returned when you registered the webhook. Compute the same digest, compare with a constant-time function (such as hash_equals in PHP), and reject requests that do not match or whose timestamp is more than 5 minutes off.
What is the correct API URL format for Moneybird?
The full pattern is: https://moneybird.com/api/v2/{administration_id}/{resource}.json for collections and https://moneybird.com/api/v2/{administration_id}/{resource}/{id}.json for individual resources. The format is part of the path, so always include it.
Sources
- Moneybird API documentation - developer.moneybird.com
- Moneybird API changelog - developer.moneybird.com/changelog
- Moneybird OpenAPI specification - GitHub
- Verifying webhook signatures - developer.moneybird.com
- Webhook events - developer.moneybird.com
- OAuth 2.0 Authorization Framework - RFC 6749, IETF
- HTTP/1.1 Semantics and Content - RFC 7231, IETF
- moneybird-python library documentation - Read the Docs
- moneybird-api-php documentation - moneybird.sandorian.com
Let's talk
We build the systems that power your business. Let us know how we can help.
Book a 30-min Call