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.
Select the Authorization tab on the request and set the Type to API Key.
Next, set the Key to "Authorization".
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..."
Make sure the Add to drop down is set to Header.
If you switch to the Headers tab on the request you should now see the Authorization header present and populated.
We will now configure the rest of the request.
In the grey bar at the top of the request, make sure the HTTP Verb dropdown is set to GET.
The URL should be populated with
https://api.expensein.com/1.0/users
, which is the endpoint to retrieve all users on the account.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.