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.