Setting up the API
Learn the basics quickly and get up and running without delay.
Introduction
With Soldo, you get smart company cards linked to intuitive management tools, so you can control, track and report spending – all in one place.
Our Business API takes that one step further, allowing you to build and manage your own custom integrations to make Soldo work for you.
This quickstart guide contains all the basic information you need to get you started, so you can be up and running with your first integration without delay.
Create your credentials
Before you start building your first integration, you’ll need to create your client credentials using the Soldo web app.
When successfully authenticated, client credentials allow requests to be made to the Soldo Business API. We recommend creating a new set of credentials for every application you want to build.
To create your credentials, log into the Soldo web app and select ‘Business API’ under ‘Integrations’ on the main nav menu.
Start the flow by clicking ‘Create application’. You’ll need to decide which application you’d like to create first and give it a name, then follow the instructions to create a key pair and enter a public key. Let's look at how to do that in more detail.
What is a key pair and why do I need one?
You need to generate a 2048 bit RSA key pair in PEM format in order to create a set of API credentials.
This key pair is made up of a public key and a private key, and is designed to ensure safe communication between the client (you) and the server (Soldo).
A public key is like a username - it's shared openly. You share this information with Soldo when creating an application. Soldo will use it to validate that it's really you making a request.
A private key is like a secret code that only you know. When you make a request, you sign a set of fields included in the request with your private key, and Soldo verifies that signature using your public key. Only requests that are successfully validated can be processed.
You'll find details on how to create a key pair using openssl during the application creation flow. Or you can find out how to do it using this Recipe:
Select your scopes
Once you've created a key pair and entered a public key, you’ll need to decide which information within Soldo your new application should be able to access.
Soldo scopes define which resources or actions an application can access within the business account.
The list of scopes enabled on your application can be retrieved from the Get who am I endpoint. It can also be viewed and edited from the web app, by going to Integrations > Business API on the main nav menu and selecting the relevant application from the list.
A full list of available scopes can be seen below:
| Scope | Description | View | Edit |
|---|---|---|---|
| Addresses | e.g. view the company address, edit shipping addresses etc. | ✔️ | ✔️ |
| Autotags | e.g. search autotags, add autotags, update autotags etc. | ✔️ | ✔️ |
| Cards | e.g. add cards, update cards, delete cards etc. | ✔️ | ✔️ |
| Company | e.g. view your company information. | ✔️ | ❌ |
| Expense category | e.g. add expense categories, update expense categories, delete expense categories etc. | ✔️ | ✔️ |
| Expense report | e.g. search expense reports, download expense reports, update expense reports etc. | ✔️ | ✔️ |
| Expense review | e.g. search expenses, update expenses, send reminders etc. | ✔️ | ✔️ |
| Groups | e.g. add groups, update groups, delete groups etc. | ✔️ | ✔️ |
| Lists | e.g. search lists, updates lists, delete lists etc. | ✔️ | ✔️ |
| Make a payment | e.g. make payments. | ✔️ | ❌ |
| Online ads | e.g. search online ads, update online ads, update assignees etc. | ✔️ | ✔️ |
| Payees | e.g. search payees, add payees, update payees etc. | ✔️ | ✔️ |
| Pre-approved spend | e.g. search spend requests, create spend requests etc. | ✔️ | ✔️ |
| Refueling transactions | e.g. search refueling transactions, update refueling transactions etc. | ✔️ | ✔️ |
| Resource sets | e.g. add resource sets, update resource sets, delete resource sets etc. | ✔️ | ✔️ |
| Roles | e.g. view roles. | ✔️ | ❌ |
| Subscriptions | e.g. search subscriptions, update subscriptions, update assignees etc. | ✔️ | ✔️ |
| Transactions | e.g. view transactions, edit transactions etc. | ✔️ | ✔️ |
| Users | e.g. search users, add users, update users etc. | ✔️ | ✔️ |
| VAT rate | e.g. add VAT rates, update VAT rates, delete VAT rates etc. | ✔️ | ✔️ |
| Vehicles | e.g. search vehicles, add vehicles, delete vehicles etc. | ✔️ | ✔️ |
| Wallets | e.g. search wallets, add wallets, perform internal transfers between wallets etc. | ✔️ | ✔️ |
| Webhook subscriptions | e.g. search webhook subscriptions, subscribe to webhooks, delete webhook subscriptions etc. | ✔️ | ✔️ |
You’ll be shown a list of available scopes during the application creation process. You can see more information on what each scope covers by clicking the name, which will open one of our Soldo support pages.
Once you’ve selected your scopes, you’ll be asked to accept the Terms and Conditions, before completing SCA verification and receiving your credentials.
Congratulations! You've successfully set up the API
Once you complete SCA verification, you'll see a popup containing your credentials:
The popup containing your credentials will only appear once, so make sure you copy and store them safely before closing it.
The Client ID and Client secret act as a username and password for your application, and are always required for standard authentication.
The Fingerprint token is an additional piece of information, and is required for advanced authentication and to decrypt URLs for downloading transaction attachments.
To learn more about the different types of authentication, click here.
And that's it! You're ready to start building your first application.
What happens if I lose my API credentials?
If you lose access to your credentials, you can regenerate them from the Soldo web app. Just go to Integrations > Business API on the main nav menu, find the relevant application from the list, and click 'Regenerate credentials'.
Regenerating your credentials will create a new Client secret and Fingerprint token. The Client ID will stay the same, as it's used to identify your application.
If you think your credentials could have been compromised in some way, consider replacing your public key by generating a new key pair and uploading it to Soldo.
Updated 9 months ago