Functional questions
Is using the the Enterprise API free?
Enterprise API is currently free to use for DKV customers. The access to specific API Services in the catalog may be subject to restriction, for specific customer groups (refer to forthcoming points for details). However, product pricing would be introduced in 2025.
Where can I find a detailed documentation for Enterprise API?
Anyone interested can register on our APIM Developer Portal and subscribe to our product to read the API Documentation.
You can test API with your own data only in the production environment.
Please note: The subscription key from the Developer Portal is not sufficient to obtain your own data. Every customer needs a technical user (OAUTH2) with their own credentials. This technical User must be requested via your DKV Sales contact person OR DKV Customer Service. It is not possible to request that via DKV API Portal.
A customer or another type of user is interested in using Enterprise API. What’s to do?
Important:
In any customer/user contact, the DKV Customer Service is the primary point of contact. The API Access cannot be requested via the API Portal.
Service request handling:
If this prospective API user is not a DKV customer yet, the user should get in touch with DKV Sales Team or DKV Customer serivce, to become a DKV customer, by signing all relevant documents and especially the general terms and conditions related to the usage of our services. The DKV customer service will initiate this process after customer has submitted formal request and signed the required documentation.
Therefore, for API Access, if the prospective API Consumer is a DKV Customer & Enterprise API Access request has been officially submitted to DKV Customer Service or Sales Contact person, the user can be onboarded and will receive his personal access data (credentials) for using of Enterprise API.
Do customers need an access credentials to utilize the Enterprise API?
Each API user requires a technical user to access the API.
Technical user consists of following attributes:
technical user's name (only a reference, not used for API Authentication/Authorization)
client ID (OAUTH2)
client secret (OAUTH2)
The Technical user name is only meant for correspondence with DKV Customer Service or other Support team, in case of questions or issues.
Additionally, an API subscription key will be created for each technical user.
The created technical user, including all attributes, will be sent to the customer via E-Mail and SMS
How can a customer request a technical user?
The customer should contact the DKV customer service or DKV Sales contact person.
Customer Service creates a new Onboarding ticket internally to DKV IT Department, with all necessary information, to initiate the next steps.
After completion of the onboarding to DKV API platform, we will send all API access credentials to the customer contact via E-mail and SMS (separated in client Id and client secret).
What kind of information is required for creating of new technical user?
To request a technical user the following information is necessary, which Customer must provide to the DKV Customer service, when applying for access to Enterprise API:
main company name
main customer number
E-Mail
mobile phone number
other customer numbers, who will be able to retrieve the data with newly created technical user
further legal documentation to be signed
Is it possible to modify attributes of an existing technical user?
The attributes of every existing technical user can be changed, excepted technical user name itself.
The request for this can be made via DKV customer Service, please use the technical username (NOT the clientId) as reference for requesting any change.
Can additional customer numbers be assigned to an existing technical user?
Additional customer numbers can also be assigned to existing technical user.
The request for this can made via DKV Customer Service, please use the technical username (NOT the clientId) as reference for requesting any change.
Are all services in the Enterprise API available to every customer?
The following services are available currently for free use, which shall however change in 2025:
Why is the OLA data not available for every customer?
Using of the OLA service requires special approval of the DKV sales lead.
How can I receive technical support regarding the Enterprise API?
For DKV customers and partners: please either contact your dedicated DKV contact or send an email to api-management@dkv-mobility.com
For interested users who are no customers yet: Please get in touch with Customer Service
How do I get all billed transactions?
All billed transactions can be retrieved in two ways:
Retrieve transactions data filtered by invoice date
Retrieve transactions data filtered by transaction date with additional filter (in request body) by invoiceStatus = INVOICED
How do I get all not billed transactions?
Retrieve transactions data filtered by transaction date with additional filter (in request body) by invoiceStatus = NOT_INVOICED
How do I get all billed passages?
All billed passages can be retrieved in two ways:
Retrieve passages data filtered by invoice date
Retrieve passages data filtered by passage end date with additional filter (in request body) by invoiceStatus = INVOICED
How do I get all not billed passages?
Retrieve passages data filtered by passage end date with additional filter (in request body) by invoiceStatus = NOT_INVOICED
Can be retrieved transactions/passages data for more than one customers in one request
This data can be requested only for one customer number per single API Request. API user can however can send multiple API requests for same customer number or different customer numbers
Which API endpoint can provide the information about all service cards?
All service cards data can be retrieved via end point: Retrieve service cards filtered by customer numbers. Service card information can be requested for max 10 customer numbers per single API request.
Which end point can provide the information about all OBUs?
All toll products data can be retrieved via end point: Retrieve toll products filtered by customer numbers. This information can be requested for max 10 customer numbers per single API Request.
OLA Service: In what format is the authorizationDateTime output?
Values in the field “authorizationDateTime” are considered as UTC.
Technical questions
What is API Request?
API request is a message sent from one computer to another through the internet, asking for specific information. It's like making a request or asking a question, and the API responds by sending back data based on that request. Every API request is directed to an API endpoint (dedicated URL) that provides access to a specific resource.
Example of API request:
curl --request POST 'https://api.dkv-mobility.com/e-api/v2.0.0/transactions/ transactionDate?size=100&page=0&customerId=1234567890&endDate=2023-04-30&startDate=2023-04-01' --header 'Authorization: bearer JhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU…--header ‘Content-Type: application/json’ --header ‘Content-Length: 0’ --header ‘ocp-apim-subscription-key: 657bf005fc5a4ttca5b8a8a4f45cb82c
How many API requests can be sent in a specific timeframe?
In order to provide efficient and performant Service to all API Users, there is a restriction regarding the API calls per second: 10 API calls per technical user per second.
Which authentication methods is supported?
Enterprise API uses Oauth2 method for authentication. JWT (Bearer token) is needed as a Header for authentication:
See example request ...--header 'Authorization: bearer JhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU…
which is valid only for 5 Minutes.
How works Oauth2 method?
OAuth2 allows the client (customer) an access to the Service with a flow „Client Credentials “
The client authenticates to the authorization server and requests an Access Token (JWT) by providing the “client credentials” (client_id and client_secret), scope and grant_type.
Example of the Token request:
curl --request POST 'https://my.dkv-mobility.com/auth/realms/enterprise-api/protocol/openid-connect/token' -H 'Content-Type: plication/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d 'client_id=[ Your Unique client_id]' -d 'client_secret=[ Your Unique client_secret]' -d 'scope=openid'
The Authorization Server authenticates the client. After successful request you will receive a JWT Bearer Token in the response.
Please insert this token as a header in your "Enterprise API" request in the header Attribute “Authorization”, and the value of the jwt token must be proceeded by prefix “bearer" <value of jwt>.
Note that the access token is valid only for 5 Minutes and a new „valid“ Access Token must be requested by API User from DKV Authorization Server before it is expired.
How is it ensured that each customer can only see their own data?
A list with customer numbers will be assigned to the technical user during onboarding process.
These customers will be listed in the token (JWT) The content of the token will be compared with a requested customer number in the API request and it will be denied if there is a mismatch.
What role does subscription key play in the E-API request?
Subscription key provides an additional protection for the API. This will be assigned during onboarding and should be added as a header in the request.
Request errors:
Each API request has a fixed URL and set of mandatory request parameters. A request with deviations from this returns follwing error response.
Similar error responses can be observed in case of missing parameters.
Defect & Incident Fixing
The API endpoint is taking a long time to send the response and customers system is timing out before the response arrives
You could increase the timeout value for your system and build in a retry mechanism. We recommend increasing the sleep time between individual retries with each attempt for optimal API Performance.
429 Too many requests
The HTTP 429 Too Many Requests response status code indicates that too many requests were sent in a given amount of time ("rate limiting").