Assure Expenses API: Getting Started

Test Client

The API Reference page contains a list of all the available endpoints (resources) of the API. Clicking on one of the resource actions will take you to a reference page for that particular resource action. This page will provide the following:

Explain what the action does.
Detail the response format in a number of content types.
Detail the request format (if it exists) in a number of content types.
Detail the request parameters (if they exist).
A test client so you can test the API actions...

Clicking the "TestClient" button brings up a dialogue box with the necessary contents to test the action, right from the help page. The response will pop up in another dialogue. You must login first at POST: Account/Login, with your Assure Expenses credentials. This returns an AuthToken, which must be present in the header of future requests (with the exception of those in the Overview page).

Making Requests

The root for all API calls is webapi.sel-expenses.com/. This means that for Budget Holders, the resource would be GET: webapi.sel-expenses.com/BudgetHolders/ Aside from the test client included in the Api Reference pages, there are a number of useful external apps and plugins that enable you to test the API.

Postman (Chrome Extension)
RESTClient (Firefox/Safari Extension)

These enable you to save requests and have other useful tools such as pretty formatting of JSON and XML. Using a plugin will speed up your adoption and understanding of the API.

Access Role Handling

The Assure Expenses solution is highly flexible; there are many areas of the product that the majority of users are not able to access. These areas are called "Spend Management Elements". This access is controlled by an elaborate access roles system:

There are a standard set of permissions that correspond to each SpendManagementElement.
Each SpendManagementElement permission can have View, Add, Update, and Delete rules.
You (or your administrator) can create an AccessRole, and sets of permissions apply to this AccessRole.
You can then apply this AccessRole to users.
A user can have multiple AccessRoles, and an AccessRole can have many users.
SpendManagementElement.API is one of these permissions...

So, as an example, you could create roles within the product such as 'Business Support' and 'Accountant':

You would assign the permission of SpendManagementElement.IPAddressFiltering (view, add, edit, delete), to the 'Business Support' role, thus enabling any member to define which IP addresses are allowed to access Assure Expenses.

You don't want an accountant (however tech savvy) to be able to accidentally ban everyone's computers from accessing Assure Expenses - so ensure the IPAddressFiltering is disabled for the 'Accountant' role. When the accountant accesses Assure Expenses, the menu option for IP Filtering will not be there, and they will not be able to access that section.

Similarly, an accountant needs to be able to create and edit currencies, but you might not want business support to do this. So you set the 'Business Support' role's SpendManagementElement.Currencies permission to "View" only. This way, anyone in that role can still see the currenciesl; just not modify the currencies in any way.

The ApiUser Role

One of the SpendManagementElements (mentioned above) is SpendManagementElement.API This is the permission that enables API access. Only the 'View' rule has any effect. You would need to create this in the Assure Expenses web site, so if it hasn't been created already, then create an AccessRole called ApiUser. Then you can simply assign that role to your user if you are allowed, or ask an administrator if you are not.

After that, provided you have the SpendManagementElement.AccessRoles permission in an AccessRole assigned to you, then you can even edit the access roles from within the API! Be careful! This feature is powerful! You could quite easily remove your own access to the API, or the AccessRoles section of the API. Be careful too that you do not give everyone else access to parts of the API that they are not allowed to use. With great power comes great responsibility!

API Errors

Being a Web API, HTTP codes are returned depending on the result of the operation. If something goes wrong, then appropriate error codes are returned where possible. These often just contain a straightforward message and an HTTP error code. Examples of this include:

You have not included the AuthToken in the header
Your AuthToken has expired
Access Roles prevent you from using an area of the API.

In addition to this, there are errors that arise as a result of incorrect object configuration. Models are checked for accuracy at the beginning of the request, and model errors will be returned if the request is bad. This covers required properties, enum validation, and dependent properties. Once this phase has passed, the objects are validated against other database objects, examples of which could be:

An EmployeeId doesn't return an actual employee
A delete of an ExpenseSubCategory fails because it is in use
Adding an object fails as one already exists in the database with the same name

These types of errors are returned along with the standard ApiResponse object. These calls are charged.