Getting Started with the API

The API is meant for developers who want to connect their applications with eHour. The API is REST-based and data is sent and received in JSON format.

Retrieve your API key

To connect with the eHour API, you must first retrieve your API key. You can access all endpoints using the API key and create clients, projects, users, etc.

To retrieve your API key:
As an Admin, log in and click the gear icon on the right and select Integrations.

The API key can be found under the label API key.

Please keep your API key safe to prevent access to your data. The API key gives full access to all your data: hours, projects, users, expenses, etc.

Authorize each request

Add your API key as an X-API-Key HTTP header to every HTTP request.

For example, replace [APIKEY] in the following curl call to retrieve all your clients:

curl -X GET --header 'X-API-Key: [APIKEY]' 'https://ehourapp.com/api/v1/clients'

If the API key is unknown or invalid, the API responds with a 401 status code

Endpoint Documentation

All the endpoints are documented in our Swagger documentation.

To call the endpoints directly from the documentation page, click on "Authorize" in the top menu and enter your API key as the "value". You can try all the requests from the documentation page.

Example: creating a client

For example, we will create a client using the API, from the documentation page. Note, that against all the standards, we are using PUT requests for creating and POST for editing.

1. Click on Authorize and add your API key
2. Click on client: Client API to view all client endpoints. Each row contains the HTTP method, the URI and a description of the endpoint.
3. Select PUT /v1/client, Create client
4. The endpoint is described in the following sections:
   • Implementation notes: a description of the endpoint.
   • Upon success the Response class and HTTP status code.
     The response class is the JSON model that is being returned. When creating entities, the generated ID is the most crucial field as you can retrieve objects on ID.
   • Parameters. A list of all expected and optional parameters. A parameter can either be a body parameter type for PUT and POST requests or a query param for GET and DELETE requests.
     The data type column holds the expected format of the parameter. For query parameters, this is in almost all cases a string while for body type parameters the data type column shows an expected model value: the body that you are supposed to send.
   • Response Messages, which HTTP status codes you can expect and for which reason. Only error status codes are shown, the success status code is shown with the earlier-mentioned response class.
5. We are going to create a client with only a name and code since the other fields are optional. Set the value of the body and click "Try it out!".
   Mind that this is not a dry run - as the label Try it Out may suggest - you are actually creating a client!

   

6. After trying it out, you will be given the actual Curl code that was executed, the request URl that was called, the headers, the response body, the response status code and the headers. That should be enough to automate your integration!

When you have connected your application with eHour, do let us know! We're more than interested in any automated integrations.

Sandbox environment

Please contact us if you want a staging environment during development. You can create a new trial account but we can also help with a non-expiring sandbox environment.

Rate limiting

Usage of the API is rate-limited to 60 calls per minute and a maximum of 5000 calls per day. Read more about efficiently using the API in this article.