General information about API usage
With the help of the be.ENERGISED API you have the possibility to automate and control functions of the software via third party systems. You can make the necessary settings in be.ENERGISED under Settings/System settings/API settings.
Please note that the API requires a paid license. |
User and system tokens are available for accessing the API. User tokens each have limited data access to the user's data, system tokens have access to all information in your client.
What is the Fleet API?
The Fleet API gives you the possibility to create CRM contact, portal user, and card. Fleet customers can then build their own registration forms for their individual fleets based on this API. The fleet drivers can then register with this user in the respective fleet APP and have the correct contract assigned immediately (registration and contract creation are deactivated in the app). The API is secured with a token that can be read from the settings page in your be.ENERGISED instance. The token must be passed as header x-api-token within each request.
Requirements to use the Fleet API
- you have created an API token in the be.ENERGISED backend
- you have configured a company (in be.ENERGISED under User Mmanagement/Companies/Registered companies)
- you have configured a billing contact
- you have configured a rate
Endpoints
The API offers two endpoints: first for providing the driver access via creating CRM contact, portal user and card (register endpoint), second for activating portal user and card (confirm endpoint).
Register Endpoint
The register endpoint creates a CRM contact, portal user, and card. The endpoint accepts the following parameters:
Request Parameters
Parameter | Required | Description |
---|---|---|
company_id | Yes | Unique company ID |
contact | Yes | contact object containing all required fields and optional fields |
user | Yes | user object containing all required fields and optional fields |
card | Yes | card object containing all required fields and optional fields |
Contact Object Parameters
Parameter | Required | Description |
---|---|---|
name | Yes | Full name of contact |
first_name | No | First name of contact |
gender | No | Gender of the contact, 0 = company, 1 = male, 2 = female |
street | No | Street of contact |
zip | No | Post code of contact |
city | No | City of contact |
country | No | Two-character country code of contact |
No | Email of contact | |
phone | No | Phone number of contact |
customer_number | No | Customer number of contact |
comment | No | Comment of contact |
User Object Parameters
Parameter | Required | Description |
---|---|---|
Yes | Email of the account | |
password | Yes | Password of the account |
account_locale | No | Account locale, e.g. de_DE |
Card Object Parameters
Parameter | Required | Description |
---|---|---|
card_no | Yes | Card number |
rate_id | Yes | UUID for the rate displayed in be.ENERGISED Rate management |
billing_contact_id | Yes | Unique billing contact identifier |
label | No | Card label |
customer_reference | No | Customer reference |
comment | No | Comment of card |
emp | No | EMP (e.g. AT-HTB) that will be assigned to the card |
Sample Request
curl --location --request POST 'https://yourinstancename.beenergised.cloud/api/fleet/v1/register' \ --header 'x-api-token: your_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "company_id": "Company UUID", "contact": { "name": "Name", "gender": "Gender", "city": "City", "customer_number": "Customer Number", "comment": "Comment" }, "user": { "email": "Email", "password": "Password", "locale": "Locale" }, "card": { "card_no": "Card Number", "rate_id": "Rate UUID", "billing_contact_id": "Billing Contact UUID" } }'
Sample Response
{ "status": "success", "data": { "contact_id": "created_contact_id", "user_id": "created_user_id", "card_id": "created_card_id" } }
Confirm Endpoint
The confirm endpoint activates the portal user and a card. The endpoint accepts the following parameters:
Request Parameters
Parameter | Required | Description |
---|---|---|
card_id | Yes | Unique card identifier |
user_id | Yes | Unique user identifier |
Sample Request
curl --location --request PUT 'https://yourinstancename.beenergised.cloud/api/fleet/v1/confirm' \ --header 'x-api-token: your_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "user_id": user_id_to_activate "card_id": card_id_to_activate, }'
Sample Response
{ "status": "success", "data": { "user_id": "activated_user_id", "card_id": "activated_card_id" } }
Version: 2022-09-15 15:58:39 UTC