Getting started

Explore the API

Our API documentation describes the endpoints available and what is required for requests made to them.

Prerequisites

Before you are able to call the API you will need a valid ExpenseIn account.  If you do not already have one please contact sales@expensein.com.

Making your first request

This example demonstrates how to retrieve a list of all users on your account. To make the request we will use the Postman HTTP tool (available for free from PostMan), however any scripting or coding language capable of creating HTTP requests can be used to interact with the ExpenseIn API.

Within an existing Postman workspace, choose Add Request to create a new request.

Firstly, the authorization must be configured for our request.

If you are planning to set up several requests within Postman you can configure Authorization at a Collection level, and allow each request in the collection to share a common authorization setup. However for the sake of simplicity in this example we will configure the request directly.

  1. Select the Authorization tab on the request and set the Type to API Key.

  2. Next, set the Key to "Authorization".

  3. In the Value field you will need to use the API key value obtained from the ExpenseIn API tab in the Integration section of the Admin area in the ExpenseIn web portal, prefixed with "ApiKey" and a space. e.g. "ApiKey abc123def456..."

  4. Make sure the Add to drop down is set to Header.

  5. If you switch to the Headers tab on the request you should now see the Authorization header present and populated.

  6. We will now configure the rest of the request.

  7. In the grey bar at the top of the request, make sure the HTTP Verb dropdown is set to GET.

  8. The URL should be populated with https://api.expensein.com/1.0/users, which is the endpoint to retrieve all users on the account.

  9. We are now ready to call the API. Press the Send button.

The API should return a JSON response with the details of all users on the account.

To explore the entire API within Postman we recommend importing the ExpenseIn OpenAPI spec from here.

Authorization

Authorization with the ExpenseIn API is done via an Authorization header, which must be present for all requests. The value of which should be:

ApiKey <apikey>

Keys can be generated from the ExpenseIn API tab in the Integration section of the Admin area in the ExpenseIn web portal.

The permissions available to a key can be configured when it is created, or later by opening Configure from the Actions menu on the key.

Conventions and Standards

URL formats

The basic URL structure for all requests is:

https://api.expensein.com/<version>/<resource>

The version segment should be of the format :

1.0

General HTTP Verb usage

GET is used to read, or query, a collection of entities the resource will be the name of the entity, e.g:

https://dev.api.expensein.com/1.0/users

GET is also used to read an individual entity, in which case the resource will be the name of the entity and the URL will also include the id of the specific entity, e.g:

https://dev.api.expensein.com/1.0/users/<id>

POST is used to create a new entity the resource will also be the name of the entity, e.g:

https://dev.api.expensein.com/1.0/users

PUT is used to update an existing entity the resource will include the id of the specific entity instance, e.g:

https://dev.api.expensein.com/1.0/users/<id>

DELETE is used to delete an existing entity the resource will include the id of the specific entity instance, e.g:

https://dev.api.expensein.com/1.0/users/<id>

Data Format

The ExpenseIn API handles requests and generates responses exclusively in JSON format.

Date and Time Handling

In the ExpenseIn API date and time data are exclusively represented as UNIX timestamps in seconds. This is the number of seconds elapsed since 1 January 1970 00:00:00 UTC. Callers to the API must convert any timestamps represented in their local timezone to UNIX timestamps (including conversion to UTC) before passing them to the API.

Limits

Requests to the ExpenseIn API are limited to 20 requests per second for each API Key on a single IP address.

If the rate limit is exceeded a HTTP 429 (Too Many Requests) response will be returned with a message similar to:

"API calls quota exceeded! maximum admitted 20 per Second."

The response will also include a Retry-After header detailing how many seconds to wait before retying.

Error Handling

If there is an error processing your request, the API will respond with an appropriate HTTP code, and if applicable include further detail in the response body as JSON.

Error Codes

401 Unauthorized

Either the API key used to authorize the request is not valid, or the user who created the key does not have the required role to perform this action.

403 Bad Request

When a request is either badly formatted, or a field within the request is invalid, the response will be a JSON formatted dictionary, keyed against the field containing the error, with the values being a collection of errors associated with that field e.g.

{
   "name": [
      "Project name is required."         
   ]
}

Structural errors will be keyed against “model” e.g.

{
   "model": [                   
      "Required property 'name' not found in JSON. Path '', line 3, position 1."             
   ]
}
404 Not Found

The resource requested was not found. If the URL contains an id then that id may not be a valid one for a resource on your account.

429 Too Many Requests

Requests are throttled to 20 per second per API key, per IP address.

Data Warehousing

Synchronisation

If you are using Data Warehousing platforms such as Power BI, and you are looking to fetch only new or updated records since the last synchronisation, please follow the guidelines below.

Endpoints such as /Expenses_Get1.0Expenses accept a parameter named lastServerChangCounter which represents the synchronisation counter you wish to retrieve data from. This is a server-side global counter.

The steps for a data synchronisation should be as follows:

  1. Retrieve the servers current counter via /ServerChangeCounter_Get. This counter is used on subsequent syncs, do not use this counter in step 2.

  2. Call the required data endpoint passing the server counter obtained during your last synchronisation, or zero, if this is your first sync.

  3. Store the counter obtained in step 1 and use for your next data sync.

It is important to use the sync counter from your previous sync as data may change between retrieving the current counter and your results being returned in step 2. By using the counter from the previous sync, you can be sure no new or modified data is missed.

Power Automate Integration

Set up the connector

  1. From the left hand menu in Power Automate, select Data > Custom Connectors

    Custom connectors

  2. From the top right menu select New custom connector > Import an OpenAPI from URL

    Import an Open API from URL

  3. Give the connector the name ExpenseInAPI, and set the URL to this.

    Click Import and then Continue.

    Set up connector 3

  4. The General tab should look like the screenshot below. Click on the Security link to move to the Security tab.

    Set up connector 4

  5. The Security tab should be setup as below.

    Set up connector 5

  6. Now click Create Connector from the top menu. You should see Saving custom connector… and after a short time your connector will be created.

    Set up connector 6

Create the connection

  1. In ExpenseIn, go to Admin > Integration and select the ExpenseIn API tab.

  2. Click New API Key

    Create the connection 1

    The following dialog allows you to customise the permissions for the key. This can be edited later if required, so you can leave the defaults in place if you are unsure what you will need.

  3. Click Add to create the key.

    Create the connection 2

  4. The key will have been created. Click the copy icon (with the two squares) next to the obfuscated key value to copy the key onto the clipboard. Or alternatively click Show key and manually copy it.

    Create the connection 3

  5. Back in Power Automate, from the left hand menu select Data > Connections

    Create the connection 4

  6. If you haven’t created a connection before you will see the following message. In which case click Create a connection.

    Create the connection 5

    Alternatively, click New connection from the top menu.

    Create the connection 6

  7. Next find the Connector you created in Part 1. Using the Search option in the top right will help filter the list. Once you have found the connector, click the +.

    Create the connection 7

    IMPORTANT!

    When entering the API Key you must prefix the value with “ApiKey”, with a following space before the key. E.g.

    ApiKey q27ce*******************

    Create the connection 8

  8. Click create. You should now see your connection in the list.

Create the connection 9

Test the connection

  1. From the left hand menu select Data > Custom connectors and click Edit (pencil) on your connector.

  2. Click tab 5. Test

  3. Select the connection created in Part 2

  4. From the Operations list select 8. Categories_Get1.0Categories and click the Test operation button

You should see an OK (200) status response, showing that your API key connection was successfully used to retrieve the list of categories on your ExpenseIn account.

test the connection