Assure Expenses API: Overview

Assure Expenses is an employee expenses system which saves time by allowing your employees to input their claims faster than a traditional paper based method, increase compliance for TAX and VAT and company policy and also realise a reduction in spend from a more efficient process.

Cut processing

Increase productivity. Reduce the amount of time spend completing, approving, processing and reimbursing employee expenses by at least 50% for all individuals involved.

Ensure policy compliance

Safeguard liabilities. Automatically collect the information required for the accurate treatment of HMRC reporting, Tax and VAT and benefits in kind.

Enhance policy management

Tighten controls. Analyse your T&E spend using our extensive reporting suite. Identify spend patterns, drill down to every item and develop policies to further reduce costs.

Comply with your corporate social responsibility

Manage your responsibilities. Measure, analyse and define your carbon footprint. Govern your duty of care to employees driving on business.

Remove bottlenecks

Free up even more time so your staff can concentrate on what they do best. Farewell to lost receipts and hello to an even smarter solution, Assure Expenses.

Spend Management has evolved over the years to handle the ever-growing variety of requirements that our customers have. We have a professional services team that works with every single client to tailor the software to the client’s needs. The employees then use the software through the https://www.sel-expenses.com/.

When you have such a large, flexible and scalable system such as Assure Expenses, clients gradually develop ways of streamlining their use of the software. Examples would be doing batch updates of currencies and exchange rates, or submitting receipts in bulk on the first of the month. Each client is different, and we do our best to build flexible software that will accommodate their needs. However, creating and then maintaining a cloud based website that caters to every client’s specific requirements all at once is nearly impossible. Even building modularly has its drawbacks. This is where the “API” comes in.

The Application Programming Interface (API) is a means to allow clients and third parties to integrate with our system by writing their own software. Essentially, we leave open a segment of our system, against which you build your own system. These two systems interact, allowing you to build specific, custom functionality. You can maintain this software yourself, and we can concentrate on adding and improving features and value to the core software.

In our case, the API is created using Microsoft’s Web API framework. This gives us a number of benefits:

• It uses Hypertext Transfer Protocol (HTTP) – which is the protocol of the world wide web
• Almost all software languages support HTTP, and a means to read and write objects
• There are ‘verbs’ – identifiers for common actions in software and data processing
• The API serves different types of content depending on your preference (XML, JSON etc.)
• Our API becomes focused on the domain objects themselves, rather than the mechanisms.

Following on from the HTTP idea, the API has been designed to be controlled in a familiar, developer-friendly way. The domain objects in Assure Expenses (Access Role, Budget Holder, Employee, etc) are mapped to 'Resources' in the API.
For each Resource, there are several HTTP verbs, which all perform different operations on the Resource:

• OPTIONS: webapi.sel-expenses.com/budgetHolders Gets a list of available actions for the resource.
• GET: webapi.sel-expenses.com/budgetHolders Gets a list of all items under this resource.
• GET: webapi.sel-expenses.com/budgetHolders/id Gets either a single resource type if you supply the id, or a list of all if not.
• GET: webapi.sel-expenses.com/budgetHolders/?Label=Ben Finds a resource by a property or combination of properties.
• POST: webapi.sel-expenses.com/budgetHolders Adds a new item to the resource, returning the item with its unique id.
• PUT: webapi.sel-expenses.com/budgetHolders/id Edits a single item with the matching id.
• PATCH: webapi.sel-expenses.com/budgetHolders/id/archive/true Performs minor edits on a resource, such as archiving or activation.
• DELETE: webapi.sel-expenses.com/budgetHolders/id Deletes the resource with this id.

You will need to be logged in and have the appropriate access roles in order to access each part of the API. The areas are restricted in the API as they are in the main Assure Expenses cloud site. You must authenticate with the API in order to gain access, which is discussed below.

The API operates a chargeable call system, which means you must be logged in and your account must have credit. You should log in with the same credentials as you would for the website. Furthermore, you must have an Access Role applied which has the API permission set, and permissions for each area of the API that you would like to access. It might be possible that you cannot change your access roles yourself; in which case you must ask your administrator.

Logging in generates an AuthToken, which must be supplied in the header of every request. Only the following actions do not require the AuthToken header (these also are NOT chargeable):

• OPTIONS: webapi.sel-expenses.com/
• OPTIONS: webapi.sel-expenses.com/{Resource}/Options
• GET: webapi.sel-expenses.com/Account/CallSatus/{CompanyId}
• POST: webapi.sel-expenses.com/Account/Login

As mentioned previously, the API operates a chargeable call system, which decrements the amount of calls you are allowed to make each time you make a call. You get free calls every day depending on the amount of claims or employees your account is configured to support. This free call limit resets itself each night at midnight - 00:00 UTC. On top of the free calls, you can also purchase licensed calls, which never expire on their own. They only decrement when you make calls and you have run out of free calls for the day. In order to throttle usage of the API and prevent overloading, there are limits to the amount of calls you can make per minute and per hour. Depending on the amount of claims your users make per month, the number of monthly complimentary API calls varies. The rates are as follows:

• 30-299: 50
• 300-599: 100
• 600-999: 500
• 1000-5999: 1000
• > 6000: 2500

Information on your call status is returned in the response to each successful call. This comes in the form of a splittable string. It can also be provided in a more formal structure by calling "api/Account/CallStatus/{CompanyId}". Use these values to determine whether or not you can finish a set of calls.

As a mechanism for change, the API returns a list of links with each response too. For each domain object (Vehicle, Team, Budget Holder etc.) there are a list of links that relate to that object. If those objects contain child domain objects, then those links are also added into the response. These links will change if the resource ever changes, so it makes sense to use these links in your applications. Making a call to any resource with the OPTIONS verb will give you back all the links for that resource.
An example would look like this:

[
    {
        "Rel":"Options",
        "Href":"webapi.sel-expenses.com/Teams",
        "Title":"OPTIONS:: Links:: The available options for Teams",
        "IsTemplated":false
    },
    {
        "Rel":"GetAll",
        "Href":"webapi.sel-expenses.com/Teams",
        "Title":"GET:: Links:: Gets single / Gets all / Finds Teams",
        "IsTemplated":false
    },
    {
        "Rel":"Get",
        "Href":"webapi.sel-expenses.com/Teams/{id}",
        "Title":"GET:: Links:: Gets single / Gets all / Finds Teams",
        "IsTemplated":true
    },
    {
        "Rel":"Find",
        "Href":"webapi.sel-expenses.com/Teams/Find?Label={Label}&Description={Description}&SearchOperator={SearchOperator}",
        "Title":"GET:: Links:: Gets single / Gets all / Finds Teams",
        "IsTemplated":true
    },
    {
        "Rel":"Post",
        "Href":"webapi.sel-expenses.com/Teams",
        "Title":"POST:: Links:: Creates new Teams",
        "IsTemplated":false
    },
    {
        "Rel":"Put",
        "Href":"webapi.sel-expenses.com/Teams/{id}",
        "Title":"PUT:: Links:: Edits single Teams",
        "IsTemplated":true
    },
    {
        "Rel":"ModifyEmployees",
        "Href":"webapi.sel-expenses.com/Teams/{id}/ModifyEmployees",
        "Title":"PATCH:: Links:: Performs minor edits on Teams",
        "IsTemplated":true
    },
    {
        "Rel":"Delete",
        "Href":"webapi.sel-expenses.com/Teams/{id}",
        "Title":"DELETE:: Links:: Deletes single Teams",
        "IsTemplated":true
    }
]

Our Web API uses REST over HTTP. This enables us to open our systems to the largest possible set of clients, and affords us benefits including, but not limited to:

• The client-server model.
• Some integrated security (HTTPS).
• Common and well known status codes.
• Custom data over a standard protocol.
• Content negotiation using Accept headers.