The developer portal will help you obtain a basic understanding of how the Vision public APIs work and how you can interact with them. The Vision APIs will allow you to develop external tools and products to import or export data from the Vision platform for your account.
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.
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 obain a token.
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.
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 via the Swagger document associated with each API. You can use the dropdown menu in the top right hand corner of each Swagger document 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 swagger document, your complete URL should be in the form of; https://test-vision-api.logistics.org.uk/{api-route}/{endpoint}. When you execute a request on the swagger document the whole URL will be displayed in the query window, allowing you to easily see how to recreate the call.
The following APIs are available:
| 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 |
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 |
404 |
The endpoint address that is being called does not exist. Please make sure your URL is correct, referring to the Swagger documents for 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 |