The public APIs are for Vision account holders who are building their own tools and products to import or export data from the Vision platform. You register an API application against your own account and work with the data belonging to that account. This portal will help you obtain a basic understanding of how the APIs work and how you can interact with them.
Before you can begin interacting with the APIs, you will first need to register an API application. This can be done via the account settings page in Vision. Give your application a recognisable name and the user role you would like your application to impersonate. Please see the user management screen for a full break down of each role and what actions your application will be able to perform. Once your application has been created, you will be given a client ID and client secret.
Please take note of the secret as you will not be able to view this again once you leave the creation screen.
The client secret will be valid for 2 years, after which you must use the manage application screen to generate a new secret and update your external tools.
There are a number of APIs that are available, each API has a specific purpose within the Vision system. You can use your bearer token to explore endpoints in the public API reference. Use the document selector at the top of the sidebar to switch between API services.
The base URL for all APIs is https://test-vision-api.logistics.org.uk/. Each individual API then has a route that needs to be applied to the base URL before the endpoint in the API reference, your complete URL should be in the form of; https://test-vision-api.logistics.org.uk/{api-route}/{endpoint}. When you send a request from the API reference the whole URL will be displayed, allowing you to easily see how to recreate the call.
| API Name | Route | Purpose |
|---|---|---|
User API |
/user |
Onboarding users into the Vision system, returning details of the application |
Reporting API |
/reporting |
Running self service reports, managing report schedules |
Employee API |
/employee |
Returning driver licence details |
Location API |
/location |
Search for your locations |
Check API |
/check |
Retrieve your checks |
The third-party APIs are for integration partners who import data into Vision on behalf of the Vision accounts that have authorised them. Unlike the public APIs, a single third-party application works across every account that has authorised it, so each request must identify the account the data belongs to. You identify the account by its member number, which you put in the endpoint path, for example /Account/{memberNumber}. If the member number is not known, or the account has not authorised your application, the request is refused with 403.
To obtain a third-party application, contact Logistics UK with the details of the integration you want to build and your application will be registered for you. You will be given a client ID and client secret in the same way as a public API application.
The base URL for the third-party APIs is https://test-vision-third-party-api.logistics.org.uk/. Each API then has a route that needs to be applied to the base URL before the endpoint in the API reference, your complete URL should be in the form of; https://test-vision-third-party-api.logistics.org.uk/{api-route}/{endpoint}. You can explore the endpoints in the third-party API reference. Use the document selector at the top of the sidebar to switch between API services.
| API Name | Route | Purpose |
|---|---|---|
Employee API |
/employee |
Importing driver card files for an authorised account |
Asset API |
/asset |
Importing vehicle unit files for an authorised account |
Once you have an application ID and secret, you can call the token endpoint to obtain a token. The flow for a token adheres to the OAuth client credentials flow, where you use your ID and secret to obtain a token. Public and third-party applications both use this flow, with the client ID and client secret they were given at registration.
The token endpoint can be found at https://login.microsoftonline.com/ftaservicestestb2c.onmicrosoft.com/oauth2/v2.0/token. The request should be a POST and the body should be form URL encoded. The token endpoint will always require the same scope, this will be https://ftaservicestestb2c.onmicrosoft.com/api/.default. An example request is as follows:
POST /ftaservicestestb2c.onmicrosoft.com/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
grant_type=client_credentials
&scope=https://ftaservicestestb2c.onmicrosoft.com/api/.default
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx
curl -d "grant_type=client_credentials&scope=https://ftaservicestestb2c.onmicrosoft.com/api/.default&client_id=xxxxxxxxxx&client_secret=xxxxxxxxxx" -X POST https://login.microsoftonline.com/ftaservicestestb2c.onmicrosoft.com/oauth2/v2.0/token
The token lifespan is 1 hour. If you continue to try to use the token after expiry, you will receive a 401 response and will need to obtain a new token.
Response codes beginning with 2 signify that a successful response has been returned from the API.
200 |
Call has been successful and the response contains the data requested (GET requests) |
201 |
Call has been successful, resource has been created and the id has been returned (POST requests) |
204 |
Call has been successful, resource has been modified or removed and there is no response to be returned (PUT, DELETE requests) |
Response codes beginning with 4 indicate there is something wrong with the request you are sending, you will need to modify your request before trying again.
400 |
The request has failed validation, please review the response message and amend your request before sending again |
401 |
Your bearer token is either incorrect, missing, or has expired, please request a new token and send your call again with the new bearer token |
403 |
The application does not have access to the resource. Either the application's role is set at a too low level, or you are trying to access a resource that doesn't belong to your account. The third-party APIs also return this code when the member number is not known, or the account has not authorised your application |
404 |
The endpoint address that is being called does not exist. Please make sure your URL is correct, checking it against the API reference |
429 |
You have exceeded the number of allowed calls in a specific time period. Please see the response headers for how long you should wait before sending again |
Response codes beginning with 5 signify a server issue, you will need to send your request again as it could not be processed.
500 |
An unexpected error occurred, the API is not able to process your request |
503 |
The API is currently unavailable. This should only be temporary, so you can try sending your request again after a small delay |
Some endpoints return additional response codes. These are listed against each endpoint in the API reference.