Getting started

Explore the API

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

https://api.expensein.com/docs/

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 http://www.postman.com), 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 https://api.expensein.com/1.0/docs.

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.

Power Automate Integration

Set up the connector

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

   

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

   

3. Give the connector the name ExpenseInAPI, and set the URL to https://api.expensein.com/1.0/docs

   Click Import and then Continue.

   

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

   

5. The Security tab should be setup as below.

   

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.

   

Create the connection

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

2. Click New API Key

   

   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.

   

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.

   

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

   

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

   

   Alternatively, click New connection from the top menu.

   

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 +.

   

   IMPORTANT!

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

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

   

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

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.