How to ask Siri about your bunq account balance, using the bunq API and Siri Shortcuts

bunq offers a world-class mobile banking solution, but wouldn’t it be great if we could make the experience even better? What about the ability to ask Siri about our current balance! That’s what we’re going to achieve in this tutorial. We will harness the power of the bunq C# SDK in combination with Siri Shortcuts to make the magic happen.

Our final product; Siri telling us if we can afford another pizza! 🍕

What do we need, for this magic to work? ✨

The shortcuts app is a powerful tool with which you can automate things in iOS, but it isn’t that powerful! You’ll have a hard time trying to make an API wrapper, inside of shortcuts, for an advanced API like the one from bunq. That’s why we will create a small proxy API in .Net Core that runs on our server or personal machine. The proxy API does the heavy-lifting, while we create an easy to use and easy to understand Siri Shortcut.

You’ll need the following items:

• .NET Core 2.2
• Visual Studio / Visual Studio Code or another IDE with support for C#
• An iPhone with the Shortcuts app installed
• A bit of programming knowledge and understanding of HTTP

I’ll be using Visual Studio (for Mac) in this tutorial, but the experience with another IDE should be similar. All the source code will be available as a download on GitHub.

Creating the .Net Core C# proxy API 🖥

We’ll need to create our own little API that the shortcut will be able to interact with. Creating a shortcut that directly talks to the bunq API will be a bit of a headache. 🤯

Setup your API project 🔨

First off, let’s open the IDE and start a new project. We’ll pick the .NET Core API project template as it gives us a nice starting point for this project. Make sure you’ll pick the latest target framework (.NET Core 2.2) and give your project a recognisable name.

Pick the API project template under the .Net Core tab.

When you’ve created the project you’ll see it already has a few files. Mainly the Startup.cs and the ValuesController.cs in the Controllers directory. We’ll use Startup.cs in a later stage to add a simple form of authentication to our API and to init the bunq SDK. But first, we’ll take a look at the ValuesController.cs in order to get a better understanding of the inner workings of a .NET Core API.

This ValuesController is what’s visible for the outside world when we run our API. The [Route(“api/[controller]”)] part tells where we can access this controller once it’s live. That is, at <yourhost>/api/values the path is derived from the controller’s name.

This ValuesController defines a few endpoints which we could call on our controller. The specific HTTP method is indicated by the HTTP verb above each endpoint.

Initialising the bunq SDK 🌈

Before we can replace the ValuesController with our own we need to add the bunq SDK to our project. Go to Project > Add NuGet Packages.. and search for bunq. Select Bunq.Sdk from the list and press Add Package. Once added, you should be able to see the bunq SDK in your solution explorer under your project dependencies.

In order to be able to use the bunq API, we’ll also need to create an apiContext. For this we’ll edit the Startup method in Startup.cs and add the following lines at the end of the method:

This piece of code tries to restore the apiContext from the local storage and if it fails (because there isn’t a local apiContext yet) it will create a new apiContext for us. The creation of the context requires three parameters:

1. The environment type (Sandbox or production)
2. A bunq API key
3. A device description

In the code sample above we’ve used two private constant strings for the API key and the device description. In order for this to work, you’ll need the following two lines to your Startup class definition.

Note: Placing your API key inside your source code isn’t best practice, but it will do for now.

We now should have a working connection with the bunq API once we run our code!

Creating the MonetaryAccountController 💰

Now that we have initialised the bunq SDK and registered our API as a device we can query the bunq API. So let’s create a new file (or duplicate the ValuesController.cs) in the Controllers directory that will handle our endpoints for retrieving account balances: MonetaryAccountController.cs

Here’s the fully finished MonetaryAccountController.cs, we’ll walk through it step by step later in the tutorial.

This file has the same structure as the old ValuesController.cs file, it contains two methods that will be exposed as API endpoints. The first method returns all monetary account and the second one returns only a specific monetary account, by providing its ID.

Before I go into more detail about the methods I’d like to redirect your attention to a small class that is defined at the top of this file. This Account class will be used as a simplified object that our API will return. This way it will be easier to process the data in the shortcuts app.

Both methods are pretty the same except the second method only returns the details of a specific method. So let me walk through the steps of the first method:

1. We load the bunqContext so we can query the bunq API.
2. We ask the bunq API the list of accounts. MonetaryAccount.List();
3. We create a list that will store our simplified Account objects
4. We iterate through the values of the MonetaryAccounts we received from the bunq API.
5. We create a simplified Account object from each MonetaryAccount and add it to our list
6. We return the list of simplified Account objects in JSON format

That’s it! That’s all that we need, in order to create a simple API that returns simplified information about our monetary accounts. You can try it out by pressing the run button and use curl or postman to call your API.

The output of our API in the terminal, using curl

Adding some security to our API 🔐

In theory, we now have a fully working API. However, everybody with the correct network path will be able to query your API once it is live. So let’s build is some security measurements.

Since our API only returns some values and the user isn’t able to add or alter data authorization by a simple API Key is enough.

First, install the AspNet.Security.ApiKey.Providers NuGet package. After that, add the following code to the ConfigureServices method in Startup.cs and add app.UseAuthentication(); before app.UseMvc(); in the Configure method.

We now have everything in place to secure our API endpoints. Just change the Super-secret-key to a strong secret and set your own name. The only thing left for us to do is adding the [Authorize] action filter to our methods in the MonetaryAccountController.cs.

And ta-da! We’ve got a fully functioning API with authorization. You’ll see that you can’t just call our endpoints without authorization. In order to call our endpoints again, we need to add an authorization HTTP header to our call, with the value: ApiKey Super-secret-key

But obviously, you’ve already changed it to something more secure 😉

In order to launch your API, you can run dotnet run in the terminal from the project’s directory.

Accessing the API from the outside 🏡

Currently, our API only runs on our own machine and isn’t available from the outside. Something we will need when we want to connect with Siri from our phone. Unfortunately, not everybody has access to a dedicated server or a static IP-address. If you have those great, run it on a server!

But for those who don’t have access to a dedicated server, we can utilise a little tool called Ngrok. Ngrok allows us to set up a secure tunnel so we can reach our API from the outside.

The steps are pretty simple:

1. Download and install ngrok
2. Register for a free account
3. run ngrok authtoken <token> to login to the ngrok tool
4. run ngrok http https://localhost:5001 (Our API runs on port 5001)

Note: You’ll get the auth token from the ngrok dashboard

The ngrok tunnel to our API

You’ll get a ngrok.io URL at which the API is available, easy as that! The tunnel is fully secured with HTTP 🔐. We can now use the ngrok URL to connect with our Siri shortcut.

Note: If you don’t login to an ngrok account the URL will only be valid for 8 hours. The URL changes every time you restart the tool.

Creating the Siri Shortcut 📱

We have our API running and available from the outside. Finally, the fun part can begin! Let’s grab our iPhone and fire up the shortcuts app. The shortcut we’re going to make only contains 4 building blocks. Let’s walk through them:

1. A URL block with the URL to our API endpoint to fetch the details of a specific account. (The ID can be obtained by calling the account list endpoint)
2. A Get Contents of URL block, where we add the Authorization header so we have access to our data.
3. We turn the data from the API into a dictionary with a Get Dictionary from Input block.
4. A Show Result block where we use the dictionary variable to present the data in the Siri response. (Get Value from Key)

That’s all we need for the shortcut! You can now add your shortcut to Siri by recording a command! Settings > Add to Siri 🎙

Our work in action, a functioning Siri shortcut! 💪

That’s it, you’re done. You’ve successfully asked Siri about your bunq account balance! Keep on tinkering! Don’t forget, the source code is available on Github.

Final notes 📝

Thanks for taking the time to read this tutorial. I hope you found it interesting and give it a try. If you liked my entry to the API tutorial contest, please give it a clap and share it. 👏

And of course, check out the other entries! 🏆