Getting started with API V2

API version 2 is the latest version of eMabler REST API. API v2 is designed to be faster, more easy to use and more scalable with larger amounts of data. Support for pagination and self managed API keys are added to API v2 when compared to API version 1. Connect is also built completely on top of API v2, so everything possible on there can be achieved by using these APIs.

Getting started

Environments

API v2 is available in the following environments:

Please note that we have split API into smaller packages, so for example Entity management (TEST: https://api.emabler.net/api/v2/cpo/) and Express (TEST: https://api.emabler.net/api/v2/express/) use different paths. Check the complete paths from the API references.

Authentication

To authenticate you first need to generate yourself an API key. To do that, you need access to Connect. With API v2 API keys are created via self service from Connect, so if you want access to Connect please contact customer service.

API keys can be created in Connect from Settings > Developer > Add API key.

Please store the API key in a secure place after creation as it cannot be accessed later from Connect.

Using the API key

Once API key is acquired, you can start calling the endpoints by adding the API key to x-api-key header.

Example curl to GET /sites in TEST:

curl -X GET "https://api.emabler.net/api/v2/cpo/v2/sites" -H  "accept: application/json" -H  "x-api-key: <API KEY>"

About permissions

An API key belongs to the operator account that created it. It has the same permissions and the same access to sites, chargers and drivers as that operator. If the operator account is missing a permission an endpoint needs, the API's error message says which one.

Because of this, the key changes along with its operator account. If the operator loses access to a site, the key loses it too. If the account is removed, integrations using its keys stop working.

Use a service account for integrations

For integrations such as the Salesforce connector, or your own systems, we recommend creating a dedicated operator account (a service account) and generating the API key from it:

1. Create a new operator in Connect, for example integrations@yourcompany.com. The email doesn't need to be a real mailbox.

2. Give it the role and site access the integration needs, and no more.

3. Navigate to the service account from Settings → Operators and assign an API Key to the account (requires global admin permission)

That way the integration doesn't depend on a single person's account, and you control what it can access in one place.

API Documentation

APIs are documented in the following pages. Please check all the available endpoints to see what is possible with API v2!

API Endpoint documentation has demo functionality built-in, so you can test the APIs directly from the documentation with your API key.