Document Version History
\nThis table shows a record of significant changes to the document.
\nDev API Url: https://devapi.lightfoot.co.uk
\nAPI Url: https://data.lightfoot.co.uk
\nThe Lightfoot Application Programming Interface (API) is a RESTful API, using the Bearer Authentication method from OAuth2. Utilising JSON as the data structure for responses.
\nThe API is designed to provide customers with direct access to product data held by Lightfoot. This document is aimed at both business and technical users to provide an understanding the data available via the API, and how to obtain it. To cater for these different audiences, this document will provide the following:
\nData and functionality available through the API
\nSecurity and Access to the API functionality
\nHow usage of the API is monitored and controlled
\nThe API uses Basic Authentication for all endpoints, and a 2-factor authentication method. All users must log in to obtain a token using their Lightfoot account credentials. Once a token has been obtained, it must then be used for further requests to obtain any data.
\nA Lightfoot account is required to login through the API and retrieve data. Please see the /login endpoint for details on how to login, and obtain a session token. Each user can only access data and entities relating to their account privilege.
\nAll API connections are encrypted using TLS (HTTPS). User sessions timeout after a period of inactivity.
\nAll successful and unsuccessful logins and usage of the API are recorded for security. Accounts are locked if 8 failed login attempts are made in consecutively, after the account password must be reset within the web portal https://my.lightfoot.co.uk/.
\nUser sessions expire after 1 hour of inactivity. If a session is no longer needed before this time then a request can be sent to the logout endpoint to terminate the current session token. More information is available in the /logout endpoint information.
\nUsage limits are in place to maintain system load and ensure consistent service for all customers. The standard limit for endpoints is 1 request per second. Exceptions are stated in the individual endpoints’ documentation.
\nShould a user reach their limit then the server will issue a 405 response with the ‘Request Limit Exceeded’ message.
\nIt is the responsibility of each API user to ensure the agreed number of requests is not exceeded. Connections may be throttled or terminated without notice if the limits are exceeded.
\nProduct usage data is available for 9 weeks from the logged / creation time.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"OVERVIEW","slug":"overview"},{"content":"AUTHENTICATION AND SECURITY","slug":"authentication-and-security"},{"content":"USAGE THRESHOLDS","slug":"usage-thresholds"},{"content":"DATA HISTORY","slug":"data-history"}],"owner":"6999201","collectionId":"53038c8c-b075-40cc-80b8-799a8b4d6981","publishedId":"SzKbNbcL","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"378642"},"publishDate":"2020-03-03T14:50:26.000Z"},"item":[{"name":"/login","event":[{"listen":"prerequest","script":{"id":"2aa70fb1-4d88-46d6-b6ad-ac4c9d764803","exec":[""],"type":"text/javascript"}}],"id":"3b097213-ae5b-4b90-8754-605c868c3a6e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{password}}"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":""},"url":"{{url}}/v1/login","description":"Used to authenticate the user. The endpoint will return a Session Id (token) to be used for all future calls to endpoints. The token (user session) expires after 1 hour of inactivity.
\nA Lightfoot username and password must be used in the authorisation header on the login Endpoint to receive a session token. For all future requests to the other endpoints, 'bearer' must be used for the username and the token as the password.
\nPlease note: when the session token expires, the server will return a 403 status response with 'Incorrect user credentials' error message.
\n","urlObject":{"path":["v1","login"],"host":["{{url}}"],"query":[],"variable":[]}},"response":[{"id":"82295c6a-6385-49db-bf5f-49c9252f1182","name":"/login","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Basic ZGVtby5lbWFpbEBkb21haW4uY28udWs6eW91cnBhc3N3b3Jk==","type":"text"}],"url":"https://data.lightfoot.co.uk/v1/login"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate","description":"Tells all caching mechanisms from server to client whether they may cache this object. It is measured in seconds"},{"key":"Connection","value":"Keep-Alive","description":"Options that are desired for the connection"},{"key":"Content-Length","value":"88","description":"The length of the response body in octets (8-bit bytes)"},{"key":"Content-Type","value":"application/json","description":"The mime type of this content"},{"key":"Date","value":"Thu, 27 Sep 2018 13:44:03 GMT","description":"The date and time that the message was sent"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT","description":"Gives the date/time after which the response is considered stale"},{"key":"Keep-Alive","value":"timeout=5, max=100","description":"Custom header"},{"key":"Pragma","value":"no-cache","description":"Implementation-specific headers that may have various effects anywhere along the request-response chain."},{"key":"Server","value":"Apache/2.4.18 (Ubuntu)","description":"A name for the server"}],"cookie":[{"expires":"Invalid Date","httpOnly":false,"domain":"192.168.33.10","path":"/","secure":false,"value":"27s8qknbnv85mccgbe5on44ch2","key":"PHPSESSID"}],"responseTime":null,"body":"{\r\n \"data\": {\r\n \"userID\": 49,\r\n \"username\": \"Lightfoot Demo\",\r\n \"vehicleCheckEnabled\": 1,\r\n \"dashcamEnabled\": null,\r\n\t\t\"userTimezone\": \"Europe/London\",\r\n \"apiToken\": \"270b1aa9aaa87f20cf5c8bd8ec8900d98f5358bd3e070a1282f70c8a2450833c\"\r\n }\r\n}"}],"_postman_id":"3b097213-ae5b-4b90-8754-605c868c3a6e"},{"name":"/logout","id":"4bf02c7e-bbfd-451e-9fb1-698f8d88b326","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{password}}"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":""},"url":"{{url}}/v1/logout","description":"Terminates the current user token.
\n","urlObject":{"path":["v1","logout"],"host":["{{url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"4bf02c7e-bbfd-451e-9fb1-698f8d88b326"},{"name":"/fleet/assignDriverRetrospectively","id":"1bcdfe2d-6ae9-444e-b07e-02c081452470","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{username}}"},{"key":"password","value":"{{password}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"assignments\": [\n {\n \"vrm\": \"ENG08ABC\",\n \"firstName\": \"Engineering\",\n \"lastName\": \"Driver1\",\n \"badgeNum\": \"ENG123\",\n \"storeNum\": \"111\",\n \"assignedFromDate\": \"2021-02-05 09:00:00\",\n \"deassignedFromDate\": \"2021-02-05 13:00:00\"\n },\n {\n \"vrm\": \"ENG08ABC\",\n \"firstName\": \"Engineering\",\n \"lastName\": \"Driver8\",\n \"badgeNum\": \"ENG130\",\n \"storeNum\": \"111\",\n \"assignedFromDate\": \"2021-02-05 13:00:00\"\n }\n ],\n \"fleetLevelID\" : 3767\n}","options":{"raw":{"language":"json"}}},"url":"{{url}}/v1/fleet/assignDriverRetrospectively","description":"Purpose: Assign drivers to vehicles retrospectively using driver names (Tesco-specific format). Processes a batch of assignments.
\nRequest contains assignments array; each item undergoes parsing and validation, with errors aggregated.
deassignedFromDate is optional; when omitted or set as string literal \"null\" (case-insensitive), it is treated as null.
On any aggregated validation/construction errors, the endpoint throws with a message of all errors prefixed by \"There are errors:\" (one per line).
Presenter returns success data; otherwise, an error with appropriate HTTP status and message is returned.
\nMethod: POST
URL: /v1/fleet/assignDriverRetrospectively
Status Codes: 200 OK, 4xx (presenter-driven), 400 Bad Request
Not applicable.
\nNot applicable.
\nNot applicable.
\nOn success: returns presenter data (implementation-defined fields representing the processed assignments).
\nOn presenter error: returns HTTP status and message determined by presenter.
\n{\n \"data\": {\n \"assignments\": [\n {\n \"vehicleID\": 26361,\n \"vrm\": \"ENG08ABC\",\n \"driverID\": 59705,\n \"firstName\": \"Engineering\",\n \"lastName\": \"Driver1\",\n \"badgeNum\": \"ENG123\",\n \"storeNum\": \"AB127\",\n \"assignedFromDate\": \"2020-02-05 09:00:00\",\n \"deassignedDate\": \"2020-02-05 13:00:00\"\n },\n {\n \"vehicleID\": 26361,\n \"vrm\": \"ENG08ABC\",\n \"driverID\": 59700,\n \"firstName\": \"Engineering\",\n \"lastName\": \"Driver8\",\n \"badgeNum\": \"ENG130\",\n \"storeNum\": \"AB127\",\n \"assignedFromDate\": \"2020-02-05 13:00:00\",\n \"deassignedDate\": null\n }\n ]\n }\n}\n\n[\n \"There are errors:\",\n \"1101: Missing data\"\n]\n\nPurpose: Deassign one or more drivers from journeys retrospectively.
\nassignments array; contents are passed to the use case.Method: PUT
URL: /v1/fleet/deassignDriverRetrospectively
Status Codes: 200 OK, 4xx (presenter-driven)
Not applicable.
\nNot applicable.
\nNot applicable.
\n{\n \"deassigned\": 5\n}\n