bunq API anatomy: Notes, attachments, and content export

bunq

Published in

bunq Developers’ Corner

5 min readOct 4, 2019

There are roughly 8 types of content you can work with via the bunq API:

Attachments in the form of images (e.g. user, company or monetary account avatars, print screens used in chats with support, images added to tabs)
Invoices
Customer (bank) statements
Relevé d’Identité Bancaire (RIB)
Annual overviews
Bills (payment statements)
QR codes
Notes (text and attachments)

On the level of API, these are covered with 14 resources embracing 62 endpoints and 192 operations in total.

While this scale offers amazing flexibility and mesmerizingly full control over the content, this power might seem scary and overwhelming at first, not to mention that finding the right endpoint can also be challenging.

Let’s look at how to work with every type of content one by one.

// General spoiler

The logics of the bunq API is such that, unless the document is uploaded and/or attached to an object, you need to create (generate) it and only then export.

Now that you know how you need to act in most cases, let’s zoom in and move to the actual cases. 🤓

Attachments

In bunq terms, attachments are images that are used as avatars of a user or a monetary account of the user or represent a real-life document such as a passport (scan).

Depending on the subtype and the object they are assigned (e.g. a user or just a note), they can be uploaded, read, listed, and sometimes exported, updated, replaced or deleted.

Let’s have a closer look at these peculiarities of every kind of attachment.

Avatars

Avatars are public images used to represent a user, company, cash register or monetary account. It’s impossible to delete them; they can only be replaced.

To add or replace an avatar for a user or a company, you need to the following:

First, upload the image via POST / attachment-public and get its attachment_public_uuid.
Then, using this UUID, you can assign the image to an object using
POST /avatar or other relevant endpoints (e.g. monetary account, user, tab or cash register endpoints).

You can export a public avatar by calling GET /attachment-public/ {attachment-publicUUID}/content.

Pro tip: Always check the models of the Request body to see all the accepted fields.

Tab attachments

If you need to add an image, such as a special deal or product, to a tab or a tab item, you need to to the following:

Upload the image via POST /user/{userID}/monetary-account/{monetary-accountID}/attachment-tab and get its ID.
Link the image via its ID to a tab or tab item using the relevant tab endpoint:

/user/{userID}/monetary-account/{monetary-accountID}/cash-register/{cash-registerID}/tab/{tabUUID}/tab-item
/user/{userID}/monetary-account/{monetary-accountID}/cash-register/{cash-registerID}/tab/{tabUUID}/tab-item-batch
/user/{userID}/monetary-account/{monetary-accountID}/cash-register/{cash-registerID}/tab-usage-multiple
/user/{userID}/monetary-account/{monetary-accountID}/cash-register/{cash-registerID}/tab-usage-single

Export of tab attachments is available via either of the two calls:

GET /tab/{tabUUID}/attachment/{attachmentID}/content or
GET /user/{userID}/monetary-account/{monetary-accountID}/attachment-tab/{attachment-tabID}/content

Note attachments

bunq allows for adding notes such as receipts, invoices or text to the following objects:

payments
draft payments
scheduled payments
batch payments
scheduled batch payments
request inquiries
request inquiry batches
request responses
iDEAL/Sofort transactions
whitelist results (auto accepted SEPA direct debits)
switch service payments
bunq.me fundraiser results
Mastercard transactions

It is possible to read, list, update and delete any note text or attachment using the relevant endpoints from the note-attachment and note-text resources.

You can export note text and attachments using GET /user/{userID}/attachment/{attachmentID}/content.

Documents and overviews

You might need to export or work with other content such as statements, invoices, annual overviews, and RIBs. They are all available for export but not always for other operations such as update or deletion. Let’s examine each kind of content one by one and see what is possible for each of them.

Statements

You can work with the period and single payment statements using the bunq API though via different API resources.

Periodic statements are statements for a period between two dates (the start and end dates) available via the customer-statement resource. When creating a new statement, you need to also specify the regional format, which could be either UK_US (comma-separated) or EUROPEAN(semicolon-separated). Other things you can do with this type of statements include the read, list, and delete operations.

To export a periodic statement, call GET /user/{userID}/monetary-account/{monetary-accountID}/customer-statement/{customer-statementID}/content.

You can create and read single payment statements using the statement resource. Their export is available via GET /user/{userID}/monetary-account/{monetary-accountID}/event/{eventID}/statement/{statementID}/ content.

Annual overview

To export an overview of a year, follow these steps:

Generate an annual overview by calling POST /user/{userID}/export-annual-overview and save its ID.
Use the ID with GET export-annual-overview/{id}/content.

You can use endpoints from the export-annual-overview resource to read and manage yearly reports.

RIB

The logic of the export annual overview applies to RIB export too:

Create a RIB by sending a POST /user/{userID}/monetary-account/{monetary-accountID}/export-rib request.
Call GET /user/{userID}/monetary-account/{monetary-accountID}/export-rib/{export-ribID}/content using the ID you received in the previous step.

It is possible to list, read, update, and delete RIBs by employing the export-rib resource.

Invoices

Invoices are manageable via two resources that embrace 5 endpoints in total. You can list and read invoices via the invoice endpoints. Unlike other documents, they have a separate endpoint for export, /user/{userID}/ invoice/{invoiceID}/pdf-content.

QR-codes

If you want to insert a bunq QR-code linked to a monetary account share invite, a tab, or a cash-register, retrieve its raw content using the following calls:

GET /user/{userID}/draft-share-invite-api-key/{draft-share-invite-api-keyID}/qr-code-content
GET /user/{userID}/draft-share-invite-bank/{draft-share-invite-bankID}/qr-code-content
GET /user/{userID}/monetary-account/{monetary-accountID}/cash-register/{cash-registerID}/tab/{tabUUID}/qr-code-content
GET /user/{userID}/monetary-account/{monetary-accountID}/cash-register/{cash-registerID}/qr-code/{qr-codeID}/content

Final tips and general overview

We have had a close-up view of the types of content you can manage using the bunq API. It’s time to zoom out and see the bigger picture.

We have compiled a table that covers the whole content functionality of our API. You will see that most export endpoints are grouped in the content resource as well as what formats of the specific type of content we support.

Try out the bunq API within seconds by just running a command in the language of your choice!

PHP

$ bash >(curl -s https://tinker.bunq.com/php/setup.sh)

PYTHON

$ bash >(curl -s https://tinker.bunq.com/python/setup.sh)

JAVA

$ bash >(curl -s https://tinker.bunq.com/java/setup.sh)

$ bash >(curl -s https://tinker.bunq.com/csharp/setup.sh)

P.S. If you’ve enjoyed the article and find it useful, let us know by giving it a clap. 😀 Subscribe to our API newsletter to never miss an API update.