NAV

Introduction

Welcome to the L10 Delivery V2 API. Our API can be used to automate the process of creating delivery quotes, bookings and the integration of real-time status updates with external systems.

The L10 Delivery V2 API is a RESTful web based API that leverages the JSON data interchange format over a secure HTTPS connection using TLS 1.2 encryption.

This document is intended to be used in conjunction with a Postman project which is supplied by LineTen (see Appendix). Postman is a collaboration platform for API development and can be used to model / test API integration through our staging environment.

The associated Postman project contains a set of example API calls which can be exchanged with our staging server to generate real-time responses. These example calls can be changed to test or model different behaviors. Please refer to the Appendix for more details.

HTTP Responses

The L10 Delivery V2 API is a RESTful HTTPS based service. Common conventions are followed, such as semantic verbs and status codes.

Status codes

The API uses HTTP codes to indicate the status of requests. This includes successful or unsuccessful responses.

Not all endpoints return all status codes, but this can be used as a guide:

Code Description
200 The request returned data successfully.
201 The request resulted in an entity being created.
202 The request was accepted for further processing.
204 The request was successful but returned no content.
400 We couldn't process your request, check the querystring/body parameters.
401 The request was not authorized.
403 The request was forbidden.
404 Endpoint not found or entity not found.
409 The state of an entity resulted in an invalid operation and was rejected.
500 Internal server error, we had a problem processing the request.

Errors

HTTP status codes from each endpoint generally indicate the source of error. All codes in the 4xx range indicate an error caused by the information supplied (e.g. a required parameter was missing), and codes in the 5xx range indicate an error on our servers.

Authentication

The L10 Delivery V2 API uses the OAuth 2.0 Authorization Framework for both Authentication and Authorization.

Authentication with the L10 Delivery V2 API is achieved using the Client Credentials grant flow.

An access_token is requested using the Client Credentials Grant and must be presented in subsequent requests Authentication with the L10 Delivery V2 API is achieved by requesting using OAuth 2.0 Bearer Token containing a JSON Web Token (JWT)

In order for any request to be made to the LineTen Delivery platform, an Authorization bearer token must be generated. This token is then sent in the Authorization: header.

Get Authorization Token

Example Authorization HTTP Request

POST https://authUrl/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=0d6a65e4-1855-4f0c-a3f0-52c1316a0707&client_secret=548296de-194f-4c7f-b393-6f4b2192589e&grant_type=client_credentials

Successful HTTP Response

{
  "access_token": "{redacted}",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "{redacted}"
}

Unsuccessful HTTP Response

{
  "error":"invalid_client"
}

Endpoint

POST https://authUrl/connect/token

Headers

Content-Type: multipart/form-data

Content

Name Type Example Value Description Required
client_id string 0d6a65e4-1855-4f0c-a3f0-52c1316a0707 Unique identifier provided by LineTen ✔
client_secret string 548296de-194f-4c7f-b393-6f4b2192589e Unique client secret provided by LineTen ✔
grant_type string client_credentials Specifies the OAuth grant type ✔

Jobs

In order to book a job, two steps need to be taken. The first step is to send a quote request, in order to investigate whether a delivery can be carried out. If one or more successful quotes are returned, the job’s status is changed to QUOTED. One of the successful quotes can be then chosen, in order to take the second step, which is to book the job.

This process can be either broken down into two separate actions:

  1. quoting and,
  2. booking.

or it can take place in one request as an immediate booking. In this case, the quote payload is sent to the immediate booking endpoint, and the job booking response payload is returned in the response body.

Bookings can also be canceled.

Quote

A Quote can be made in the context of a "Client" or a "Store".

The difference when booking against a Store is that the pickup address is replaced by an ExtStoreRef field.

Client Quote Request Payload

Store Quote Request Payload

Successful Quote Response: 201

Unsuccessful Quote Response: 400

Client Quote Request Payload

 {
  "TransportType": [
    "motorbike",
    "car"
  ],
  "Tasks": [
    {
      "Type": "pickup",
      "Flags": [
        "signature"
      ],
      "Tags": [],
      "Notes": "",
      "Items": [
        {
          "Package": {
            "Size": "M"
          }
        },
        {
          "Package": {
            "Size": "M"
          }
        }
      ],
      "Location": {
        "Address": {
          "CompanyName": "LineTen",
          "Address1": "Unit 1",
          "Address2": "",
          "Postcode": "W12 7FP",
          "City": "London",
          "Country": "England",
          "County": "",
          "Notes": ""
        },
        "Persons": [
          {
            "Phone": "07934123456",
            "FirstName": "John",
            "LastName": "Smith",
            "Email": "",
            "Notes": ""
          }
        ],
        "GeoLocation": {
          "Latitude": 51.51337958957683,
          "Longitude": -0.227849427489506
        }
      }
    },
    {
      "Type": "delivery",
      "RequestedTime": "2020-08-19T11:30:00",
      "RequestedWindow": {
        "From": "2020-08-19T11:30:00",
        "To": "2020-08-19T14:30:00"
      },
      "Flags": [
        "scan_barcode"
      ],
      "Tags": [
        "fragile"
      ],
      "Notes": "",
      "Location": {
        "Address": {
          "CompanyName": "",
          "Address1": "55 Woodsford Square",
          "Address2": "",
          "Postcode": "W14 8DS",
          "City": "London",
          "Country": "England",
          "County": "",
          "Notes": ""
        },
        "Persons": [
          {
            "FirstName": "George",
            "LastName": "King",
            "Phone": "07934123456",
            "Email": "",
            "Notes": ""
          }
        ],
        "GeoLocation": {
          "Latitude": 51.50314712524414,
          "Longitude": -0.20904703438282013
        }
      },
      "Items": [
        {
          "Package": {
            "Size": "M"
          }
        },
        {
          "Package": {
            "Size": "M"
          }
        }
      ]
    }
  ]
}

Store Quote Request Payload

{
  "TransportType": [
    "motorbike",
    "car"
  ],
  "Tasks": [
    {
      "Type": "pickup",
      "Flags": [
        "signature"
      ],
      "Tags": [],
      "Labels": [],
      "Notes": "",
      "Items": [
        {
          "Package": {
            "Size": "M"
          }
        }
      ],
      "Location": {
        "ExtStoreRef": "xxx"
      }
    },
    {
      "Type": "delivery",
      "RequestedTime": "2020-08-19T11:30:00",
      "RequestedWindow": {
        "From": "2020-08-19T11:30:00",
        "To": "2020-08-19T14:30:00"
      },
      "Flags": [
        "scan_barcode"
      ],
      "Tags": [
        "fragile"
      ],
      "Labels": [],
      "Notes": "",
      "Location": {
        "Address": {
          "CompanyName": "",
          "Address1": "55 Woodsford Square",
          "Address2": "",
          "Postcode": "W14 8DS",
          "City": "London",
          "Country": "England",
          "County": "",
          "Notes": ""
        },
        "Persons": [
          {
            "FirstName": "George",
            "LastName": "King",
            "Phone": "07934123456",
            "Email": "",
            "Notes": ""
          }
        ],
        "GeoLocation": {
          "Latitude": 51.50314712524414,
          "Longitude": -0.20904703438282013
        }
      },
      "Items": [
        {
          "Package": {
            "Size": "M"
          }
        }
      ]
    }
  ]
}

Successful Quote Response returns 201

 {
  "info": {
    "status": 201,
    "requestId": "eb30aff5-e016-4515-b9d7-d319bac4941c",
    "method": "POST",
    "endpoint": "\/v2\/nds\/quote",
    "error": false,
    "errorMessages": [],
    "timestamp": 1628495762,
    "timezone": "europe\/london",
    "timing": 16.8954,
    "rows": 18
  },
  "payload": {
    "QuoteRequestId": "b8a8c2e7-4d04-4ea7-4b56-08d957fb5b20",
    "JobUuid": "39d5d635-3134-4ae6-a7ff-4c481f8f9533",
    "Id": 30890,
    "TransactionId": "66a23eff-1e26-459c-b264-0a4ad16411aa",
    "ExpiresAt": "2021-08-23T03:56:01",
    "ClientRef": "",
    "Notes": "",
    "EntityId": 5427,
    "TransportType": [
      "motorbike",
      "car"
    ],
    "SelectedQuote": 0,
    "AssignedDriver": 0,
    "Status": "quoted",
    "DeliveryStatus": "pending",
    "Documents": [],
    "CallbackUrl": "",
    "ProcessedDates": {
      "RequestedPickupStart": null,
      "RequestedPickupEnd": null,
      "RequestedDeliveryStart": "2021-08-09T11:30:00",
      "RequestedDeliveryEnd": "2021-08-09T14:30:00",
      "ExpectedJobPickup": "2021-08-09T03:55:50",
      "ExpectedJobComplete": "2021-08-09T11:30:00",
      "ActualJobPickup": "0000-00-00T00:00:00",
      "ActualJobComplete": "0000-00-00T00:00:00"
    },
    "Tasks": [
      {
        "Id": 62818,
        "Type": "pickup",
        "TransportType": [
          "car"
        ],
        "TaskStatus": "to_do",
        "ProcessedDates": {
          "RequestedTimeStart": "0000-00-00T00:00:00",
          "RequestedTimeEnd": "0000-00-00T00:00:00",
          "ExpectedTimeComplete": "0000-00-00T00:00:00",
          "ActualTimeComplete": "0000-00-00T00:00:00"
        },
        "Flags": [
          "signature"
        ],
        "Tags": [],
        "Labels": [],
        "Location": {
          "LocationId": 9627,
          "Type": "pickup_address",
          "Address": {
            "CompanyName": "LineTen",
            "Address1": "Unit 1",
            "Address2": "",
            "Postcode": "W12 7FP",
            "City": "London",
            "Country": "England",
            "County": "London",
            "Notes": ""
          },
          "GeoLocation": {
            "Latitude": 51.513379589577,
            "Longitude": -0.22784942748951
          },
          "Persons": [
            {
              "Id": 60478,
              "FirstName": "John",
              "LastName": "Smith",
              "Phone": "07934806619",
              "Email": "",
              "Notes": ""
            }
          ]
        },
        "Notes": "",
        "Items": [
          {
            "Id": 49702,
            "Ref": "",
            "Notes": "blah",
            "ItemCount": 1,
            "Package": {
              "Size": "m"
            }
          }
        ]
      },
      {
        "Id": 62819,
        "Type": "delivery",
        "TransportType": [
          "car"
        ],
        "TaskStatus": "to_do",
        "ProcessedDates": {
          "RequestedTimeStart": "2021-08-09T11:30:00",
          "RequestedTimeEnd": "2021-08-09T14:30:00",
          "ExpectedTimeComplete": "2021-08-09T14:30:00",
          "ActualTimeComplete": "0000-00-00T00:00:00"
        },
        "Flags": [
          "scan_barcode"
        ],
        "Tags": [
          "fragile"
        ],
        "Labels": [],
        "Location": {
          "LocationId": 13330,
          "Type": "delivery_address",
          "Address": {
            "CompanyName": "Receiver",
            "Address1": "De Burgh Gardens",
            "Address2": "",
            "Postcode": "KT20 5LH",
            "City": "Tadworth",
            "Country": "England",
            "County": "Surrey",
            "Notes": ""
          },
          "GeoLocation": {
            "Latitude": 51.503147125244,
            "Longitude": -0.20904703438282
          },
          "Persons": [
            {
              "Id": 60479,
              "FirstName": "George",
              "LastName": "King",
              "Phone": "07934123456",
              "Email": "",
              "Notes": ""
            }
          ]
        },
        "Notes": "",
        "Items": [
          {
            "Id": 49703,
            "Ref": "",
            "Notes": "blah",
            "ItemCount": 1,
            "Package": {
              "Size": "m"
            }
          }
        ]
      }
    ],
    "Quotes": [
      {
        "Id": null,
        "QuoteResponseId": "0a3de489-d298-4d81-2f70-08d957fe03d3",
        "JobId": 30890,
        "ClientId": 5427,
        "EntityId": 5427,
        "TransportTypes": [
          "motorbike"
        ],
        "QuoteStatus": "quoted",
        "DeliveryProviderId": null,
        "DeliveryProviderUuid": "366a0553-8d69-4332-aa44-791f4d9f2688",
        "DeliveryProviderCurrency": "GBP",
        "DeliveryProviderMeasurement": "metric",
        "ClientMeasurementUnit": "metric",
        "ProviderQuoteId": "",
        "ProviderJobId": "",
        "ProviderFriendlyJobId": null,
        "Distance": 28.826,
        "QuotedPrice": 7.05,
        "FinalTotalAmount": 0,
        "CancellationFee": 0,
        "ExpireAt": "2021-08-09T04:55:59",
        "BookedTime": "0000-00-00T00:00:00",
        "ProviderNotes": "",
        "Attachments": []
      },
      {
        "Id": null,
        "QuoteResponseId": "e0ebb20c-133d-4aa4-2f71-08d957fe03d3",
        "JobId": 30890,
        "ClientId": 5427,
        "EntityId": 5427,
        "TransportTypes": [
          "car"
        ],
        "QuoteStatus": "quoted",
        "DeliveryProviderId": null,
        "DeliveryProviderUuid": "366a0553-8d69-4332-aa44-791f4d9f2688",
        "DeliveryProviderCurrency": "GBP",
        "DeliveryProviderMeasurement": "metric",
        "ClientMeasurementUnit": "metric",
        "ProviderQuoteId": "",
        "ProviderJobId": "",
        "ProviderFriendlyJobId": null,
        "Distance": 28.826,
        "QuotedPrice": 9.5,
        "FinalTotalAmount": 0,
        "CancellationFee": 0,
        "ExpireAt": "2021-08-09T04:56:00",
        "BookedTime": "0000-00-00T00:00:00",
        "ProviderNotes": "",
        "Attachments": []
      }
    ]
  }
}

Unuccessful Quote Response returns 400

  {
   "info":{
      "status":400,
      "requestId":"b1e7b8bc-a2cf-442d-a568-ae124bc62cb2",
      "method":"POST",
      "endpoint":"\\/v2\\/nds\\/quote",
      "error":true,
      "errorMessages":[

      ],
      "timestamp":1597780364,
      "timezone":"Europe\\/London",
      "timing":0.0777,
      "rows":0
   },
   "payload":null
  }

Endpoint:

POST apiUrl/v2/nds/quote

Headers:

Authorization: Bearer {bearer_token}

Content-Type: application/json

QuoteRequest Fields:

Name Type Value Description Required
TransportType string[] walker, bike, cargobike, motorbike, car, van, truck, any, minivan The transport type the quote is sent for ✔
DeliveryProvider string[] Name of delivery provider The delivery provider(s) to request quotes from
CallbackUrl string The endpoint for receiving callbacks for the job
Flags string[] scan_barcode, photo_item, c25, signature, c30 Contains the potential driver actions for the job
Tags string[] hot, frozen, fragile, controlled_drug, refrigerated Contains the potential item attributes of the job
Notes string Notes for the job
ClientRef string The client job reference
Tasks Task[] See Task Fields The tasks of the job. One pickup and one delivery task must be included. ✔

Task Fields:

Name Type Value Description Required
Type string Pickup delivery The type of the task ✔
TransportType string[] walker bike, cargobike, motorbike, car, van, truck, any, minivan The transport type the quote is sent for
RequestedTime string The date and time requested for the task.
RequestedWindow RequestedWindow[] See RequestedWindow Fields The date and time window for the task If this exists then RequestedTime is ignored
Flags string[] scan_barcode, photo_item, c25, signature, c30 Contains the potential driver actions for a task
Tags string[] hot, frozen, fragile, controlled_drug, refrigerated Contains the potential item attributes of a task
Notes string Notes for the task
Items Item[] See Item Fields The items of a task ✔
Location Location See Location Fields The location of the task ✔

RequestedWindow Fields:

Name Type Format Description Required
From string The date and time requested from ✔
To string The data and time requested to ✔

Item Fields:

Name Type Description Required
Package Package The package of an item. See Package Fields ✔

Package Fields:

Name Type Description Required
Size string Possible Values S M L XL The size of a package ✔

Location Fields:

Name Type Description Required
Address Address The address of a location See Address Fields ✔
Persons Person[] The persons for a task See Person Fields
GeoLocation GeoLocation Contains lat/long coordinates of the task location See GeoLocation Fields ✔
ExtStoreRef string The external store reference that needs to be sent when booking on behalf of a store. When this field is present all the other Location fields are ignored

Address Fields:

Name Type Description Required
CompanyName string
Address1 string
Address2 string
Postcode string ✔
City string ✔
County string
Country string ✔
Notes string Notes for the address

Persons Fields:

Name Type Description Required
Phone string
FirstName string
LastName string ✔
Email string
Notes string Notes for the Person

GeoLocation Fields:

Name Type Description Required
Latitude float ✔
Longitude float ✔

QuoteResponse Fields:

Name Type Description
info Info Response info See Info Fields
payload Payload Response payload See Payload Fields

Info Fields:

Name Type Description
status string The HTTP response status
requestId string Request unique identifier
method string The HTTP method
endpoint string The nds request endpoint
error bool Response success
errorMessages string[] Contains the error messages (in case of error response)
timestamp integer Unix timestamp of the request
timezone string The time zone of the request
timing float The response time of the request
rows integer The number of rows returned

Payload Fields:

Name Type Description
Id integer The quote response id
TransactionId string A unique identifier attached to the request
ExpiresAt string The quote expiration date time
ClientRef string The Client reference of the request
EntityId integer The id of the entity the quote belongs to
TransportType string[] Possible Values walker bike cargobike motorbike car van The transport types of the quote request
SelectedQuote integer The id of the selected quote (in case the job has been booked)
AssignedDriver integer The id of the driver assigned to the job (in case the job has been booked)
Status string The status of the quote
DeliveryStatus string The delivery status of the quote
CallbackUrl string The callback URL which was sent in the quote request
ProcessedDates ProcessedDates[] The date fields of the job See ProcessedDates Fields
Quotes Quote[] The returned quotes See Quote Fields
Tasks Task[] The job tasks See Task Fields

ProcessedDates Fields:

Name Type Description
RequestPickupStart string The requested pickup start datetime
RequestedPickupEnd string The requested pickup end datetime
RequestDeliveryStart string The requested delivery start datetime
RequestedDeliveryEnd string The requested delivery end datetime
ExpectedJobPickup string The expected job pickup datetime
ExpectedJobComplete string The expected job completion datetime
ActualJobPickup string The actual job pickup datetime
ActualJobComplete string The actual job completion datetime

Quote Fields:

Name Type Description
Id integer The quote id
JobId integer The id of the job the quote belongs to
ClientId integer The client the job was booked for
EntityId integer The client / store the job was booked for (In case the job was booked for a client it has the same value as ClientId)
TransportTypes string[] Possible Values walker bike cargobike motorbike car van The transport types of the quote
QuoteStatus string The status of the quote
DeliveryProviderId integer The id of the Delivery Provider the quote belongs to
DeliveryProviderCurrency string The currency of the Delivery Provider
DeliveryProviderMeasurement string The measurement unit of the Delivery Provider
ProviderQuoteId string The Delivery Provider quote id
ProviderJobId string The Delivery Provider job id
Distance float The distance between the pickup and the delivery address
FinalTotalAmount float The total price of the quote
CancellationFee float The cancellation fee of the quote (in case the job gets booked using this quote)
ExpireAt string The quote expiration date time
BookedTime string The time the quote was booked (in case the job gets booked using this quote)
ProviderNotes string The notes of the Delivery Provider

Booking

Once a quote has been created, it can be booked by calling the booking request endpoint

Booking Payload

Successful Booking Response: 201

Unsuccessful Booking Response: 400

Booking Payload

 {
   "JobId": 30890,
   "QuoteResponseId": "0a3de489-d298-4d81-2f70-08d957fe03d3"
  }

Successful Booking Response returns 201

{
   "info": {
    "status": 201,
    "requestId": "eb30aff5-e016-4515-b9d7-d319bac4941c",
    "method": "POST",
    "endpoint": "\/v2\/nds\/quote",
    "error": false,
    "errorMessages": [],
    "timestamp": 1628495762,
    "timezone": "europe\/london",
    "timing": 16.8954,
    "rows": 18
  },
  "payload": {
    "QuoteRequestId": "b8a8c2e7-4d04-4ea7-4b56-08d957fb5b20",
    "JobUuid": "39d5d635-3134-4ae6-a7ff-4c481f8f9533",
    "Id": 30890,
    "TransactionId": "66a23eff-1e26-459c-b264-0a4ad16411aa",
    "ExpiresAt": "2021-08-23T03:56:01",
    "ClientRef": "",
    "Notes": "",
    "EntityId": 5427,
    "TransportType": [
      "motorbike",
      "car"
    ],
    "SelectedQuote": 0,
    "AssignedDriver": 0,
    "Status": "quoted",
    "DeliveryStatus": "pending",
    "Documents": [],
    "CallbackUrl": "",
    "ProcessedDates": {
      "RequestedPickupStart": null,
      "RequestedPickupEnd": null,
      "RequestedDeliveryStart": "2021-08-09T11:30:00",
      "RequestedDeliveryEnd": "2021-08-09T14:30:00",
      "ExpectedJobPickup": "2021-08-09T03:55:50",
      "ExpectedJobComplete": "2021-08-09T11:30:00",
      "ActualJobPickup": "0000-00-00T00:00:00",
      "ActualJobComplete": "0000-00-00T00:00:00"
    },
    "Tasks": [
      {
        "Id": 62818,
        "Type": "pickup",
        "TransportType": [
          "car"
        ],
        "TaskStatus": "to_do",
        "ProcessedDates": {
          "RequestedTimeStart": "0000-00-00T00:00:00",
          "RequestedTimeEnd": "0000-00-00T00:00:00",
          "ExpectedTimeComplete": "0000-00-00T00:00:00",
          "ActualTimeComplete": "0000-00-00T00:00:00"
        },
        "Flags": [
          "signature"
        ],
        "Tags": [],
        "Labels": [],
        "Location": {
          "LocationId": 9627,
          "Type": "pickup_address",
          "Address": {
            "CompanyName": "LineTen",
            "Address1": "Unit 1",
            "Address2": "",
            "Postcode": "W12 7FP",
            "City": "London",
            "Country": "England",
            "County": "London",
            "Notes": ""
          },
          "GeoLocation": {
            "Latitude": 51.513379589577,
            "Longitude": -0.22784942748951
          },
          "Persons": [
            {
              "Id": 60478,
              "FirstName": "John",
              "LastName": "Smith",
              "Phone": "07934806619",
              "Email": "",
              "Notes": ""
            }
          ]
        },
        "Notes": "",
        "Items": [
          {
            "Id": 49702,
            "Ref": "",
            "Notes": "blah",
            "ItemCount": 1,
            "Package": {
              "Size": "m"
            }
          }
        ]
      },
      {
        "Id": 62819,
        "Type": "delivery",
        "TransportType": [
          "car"
        ],
        "TaskStatus": "to_do",
        "ProcessedDates": {
          "RequestedTimeStart": "2021-08-09T11:30:00",
          "RequestedTimeEnd": "2021-08-09T14:30:00",
          "ExpectedTimeComplete": "2021-08-09T14:30:00",
          "ActualTimeComplete": "0000-00-00T00:00:00"
        },
        "Flags": [
          "scan_barcode"
        ],
        "Tags": [
          "fragile"
        ],
        "Labels": [],
        "Location": {
          "LocationId": 13330,
          "Type": "delivery_address",
          "Address": {
            "CompanyName": "Receiver",
            "Address1": "De Burgh Gardens",
            "Address2": "",
            "Postcode": "KT20 5LH",
            "City": "Tadworth",
            "Country": "England",
            "County": "Surrey",
            "Notes": ""
          },
          "GeoLocation": {
            "Latitude": 51.503147125244,
            "Longitude": -0.20904703438282
          },
          "Persons": [
            {
              "Id": 60479,
              "FirstName": "George",
              "LastName": "King",
              "Phone": "07934123456",
              "Email": "",
              "Notes": ""
            }
          ]
        },
        "Notes": "",
        "Items": [
          {
            "Id": 49703,
            "Ref": "",
            "Notes": "blah",
            "ItemCount": 1,
            "Package": {
              "Size": "m"
            }
          }
        ]
      }
    ],
    "Quotes": [
      {
        "Id": null,
        "QuoteResponseId": "0a3de489-d298-4d81-2f70-08d957fe03d3",
        "JobId": 30890,
        "ClientId": 5427,
        "EntityId": 5427,
        "TransportTypes": [
          "motorbike"
        ],
        "QuoteStatus": "quoted",
        "DeliveryProviderId": null,
        "DeliveryProviderUuid": "366a0553-8d69-4332-aa44-791f4d9f2688",
        "DeliveryProviderCurrency": "GBP",
        "DeliveryProviderMeasurement": "metric",
        "ClientMeasurementUnit": "metric",
        "ProviderQuoteId": "",
        "ProviderJobId": "",
        "ProviderFriendlyJobId": null,
        "Distance": 28.826,
        "QuotedPrice": 7.05,
        "FinalTotalAmount": 0,
        "CancellationFee": 0,
        "ExpireAt": "2021-08-09T04:55:59",
        "BookedTime": "0000-00-00T00:00:00",
        "ProviderNotes": "",
        "Attachments": []
      },
      {
        "Id": null,
        "QuoteResponseId": "e0ebb20c-133d-4aa4-2f71-08d957fe03d3",
        "JobId": 30890,
        "ClientId": 5427,
        "EntityId": 5427,
        "TransportTypes": [
          "car"
        ],
        "QuoteStatus": "quoted",
        "DeliveryProviderId": null,
        "DeliveryProviderUuid": "366a0553-8d69-4332-aa44-791f4d9f2688",
        "DeliveryProviderCurrency": "GBP",
        "DeliveryProviderMeasurement": "metric",
        "ClientMeasurementUnit": "metric",
        "ProviderQuoteId": "",
        "ProviderJobId": "",
        "ProviderFriendlyJobId": null,
        "Distance": 28.826,
        "QuotedPrice": 9.5,
        "FinalTotalAmount": 0,
        "CancellationFee": 0,
        "ExpireAt": "2021-08-09T04:56:00",
        "BookedTime": "0000-00-00T00:00:00",
        "ProviderNotes": "",
        "Attachments": []
      }
    ]
  }
}

Unsuccessful Booking Response returns 400

  {
   "info":{
      "status":400,
      "requestId":"cb406aee-e591-4651-8f91-97c0a2e0c123",
      "method":"POST",
      "endpoint":"\\/v2\\/nds\\/booking",
      "error":true,
      "errorMessages":[

      ],
      "timestamp":1597780605,
      "timezone":"Europe\\/London",
      "timing":0.0702,
      "rows":0
   },
   "payload":null
  }

Endpoint:

POST apiUrl/v2/nds/booking

Headers:

Authorization: Bearer {bearer_token}

Content-Type: application/json

Job Request Fields:

Name Type Description Required
JobId integer The job id produced by the quote request ✔
QuoteResponseId string The quote id produced by the quote request ✔
CallbackUrl string The endpoint for receiving callbacks for the job
ClientRef string The client job reference

Job Response Fields:

Name Type Description
info Info Response info - See Info Fields
payload Payload Response payload - See Payload Fields

Info Fields:

Name Type Description
status string The HTTP response status
requestId string Request unique identifier
method string The HTTP method
endpoint string The nds request endpoint
error bool Response success
errorMessages string[] Contains the error messages (in case of error response)
timestamp integer Unix timestamp of the request
timezone string The timezone of the request
timing float The response time of the request
rows integer The amount of rows returned

Payload Fields:

Name Type Description
Id integer The job id
TransactionId string A unique identifier attached to the request
ExpiresAt string The quote expiration date time
ClientRef string The Client reference of the request
EntityId integer The id of the entity the quote belongs to
TransportType string[] Possible Values walker bike cargobike motorbike car van The transport types of the quote request
SelectedQuote integer The id of the selected quote
AssignedDriver integer The id of the driver assigned to the job
Status string The status of the quote
DeliveryStatus string The delivery status of the quote
CallbackUrl string The callback URL which was sent in the quote request
ProcessedDates ProcessedDate[] The date fields of the job - See ProcessedDate Fields
Quotes Quote[] The quotes of the job - See Quote Fields
Tasks Task[] The tasks of the job - See Task Fields
Tracker Tracker The tracker URLs - See Tracker Fields

Task Fields:

Name Type Description
Id integer The task id
Type string Possible Values pickup delivery The type of the task
TransportType string[] Possible Values walker bike cargobike motorbike car van truck any minivan The transport type the quote is sent for
Flags string[] Possible Values scan_barcode photo_item c25 signature c30 Contains the potential driver actions for a task
Tags string[] Possible Values hot frozen fragile controlled_drug refrigerated Contains the potential item attributes of a task
Notes string Notes for the task
Items Item[] The items of a task - See Item Fields
Location Location The location of the task - See Location Fields

Item Fields:

Name Type Description
Id integer The item id
Package Package The package of an item - See Package Fields

Location Fields:

Name Type Description
Address Address The address of a location - See Address Fields
Persons Person The persons for a task - See Person Fields
GeoLocation GeoLocation Contains lat/long coordinates of the task location - See Address Fields
ExtStoreRef string The external store reference that needs to be sent when booking on behalf of a store. When this field is present all the other Location fields are ignored

Address fields

Name Type Description
CompanyName string
Address1 string
Address2 string
Postcode string
City string
County string
Country string
Notes string Notes for the Address

Person Fields:

Name Type Description
Phone string
FirstName string
LastName string
Email string
Notes string Notes for the Person

GeoLocation Fields:

Name Type Description Required
Latitude float ✔
Longitude float ✔

ProcessedDates Fields:

Name Type Description
RequestPickupStart string The requested pickup start datetime
RequestedPickupEnd string The requested pickup end datetime
RequestDeliveryStart string The requested delivery start datetime
RequestedDeliveryEnd string The requested delivery end datetime
ExpectedJobPickup string The expected job pickup datetime
ExpectedJobComplete string The expected job completion datetime
ActualJobPickup string The actual job pickup datetime
ActualJobComplete string The actual job completion datetime

Quote Fields:

Name Type Description
Id integer The quote id
JobId integer The id of the job the quote belongs to
ClientId integer The client the job was booked for
EntityId integer The client / store the job was booked for (In case the job was booked for a client it has the same value as ClientId)
TransportTypes string[] Possible Values walker bike cargobike motorbike car van The transport types of the quote
QuoteStatus string The status of the quote
DeliveryProviderId integer The id of the Delivery Provider the quote belongs to
DeliveryProviderCurrency string The currency of the Delivery Provider
DeliveryProviderMeasurement string The measurement unit of the Delivery Provider
ProviderQuoteId string The Delivery Provider quote id
ProviderJobId string The Delivery Provider job id
Distance float The distance between the pickup and the delivery address
FinalTotalAmount float The total price of the quote
CancellationFee float The cancellation fee of the quote (in case the job gets booked using this quote)
ExpireAt string The quote expiration date time
BookedTime string The time the quote was booked (in case the job gets booked using this quote)
ProviderNotes string The notes of the Delivery Provider

Tracker Fields:

Name Type Description
Pickup string The pickup tracking URL
Delivery string The delivery tracking URL
Complete string The complete tracking URL

Immediate Booking

Immediate Booking Payload - see Client Quote Request

Immediate Booking Successful Response - see Successful Quote Response

Immediate Booking Unsuccessful Response - see Unsuccessful Quote Response

Endpoint:

POST apiUrl/v2/nds/immediateBooking

Headers:

Authorization: Bearer {bearer_token}

Content-Type: application/json

When the call is made to apiUrl/v2/nds/immediateBooking, the L10 Delivery solution quotes and then book the job internally, picking the best quote based on a set of rules. The format of the Quote request for an Immediate Booking is the same as a normal Quote.

Cancellation

Successful Cancel Response: 200

Unsuccessful Cancel Response: 400

Cancellation Request

POST https://apiUrl/v2/job/cancel/{jobId} HTTP/1.1

Successful Cancel Response returns 200

  {
   "info":{
      "status":200,
      "requestId":"4c11b143-e1a8-4c65-9b8d-4ca45ce33b51",
      "method":"PUT",
      "endpoint":"\\/v2\\/job\\/cancel\\/33511",
      "error":false,
      "errorMessages":[

      ],
      "timestamp":1625478455,
      "timezone":"europe\\/london",
      "timing":2.625,
      "rows":1
   },
   "payload":[
      {
         "Id":null,
         "QuoteResponseId":"0a3de489-d298-4d81-2f70-08d957fe03d3",
         "JobId":30890,
         "ClientId":5427,
         "EntityId":5427,
         "TransportTypes":[
            "any"
         ],
         "QuoteStatus":"archived",
         "DeliveryProviderId":null,
         "DeliveryProviderUuid":"16045f5f-e687-4731-1d39-08d9364eb044",
         "DeliveryProviderCurrency":"USD",
         "DeliveryProviderMeasurement":"metric",
         "ClientMeasurementUnit":"metric",
         "ProviderQuoteId":"",
         "ProviderJobId":"4920788",
         "Distance":0.07,
         "QuotedPrice":0,
         "FinalTotalAmount":0,
         "CancellationFee":0,
         "ExpireAt":"2021-07-05T05:50:25",
         "BookedTime":"0000-00-00T00:00:00",
         "ProviderNotes":"NOVA generated quote",
         "Attachments":[
            {
               "id":"563977e0-c7df-442a-f6b5-08d93a5b1451",
               "filename":"4920788.pdf",
               "fileType":"DeliveryLabel",
               "contentType":"application\\/pdf"
            }
         ]
      }
   ]
  }

Unsuccessful Cancel Response returns 400

  {
   "info":{
      "status":200,
      "requestId":"4c11b143-e1a8-4c65-9b8d-4ca45ce33b51",
      "method":"PUT",
      "endpoint":"\\/v2\\/job\\/cancel\\/33511",
      "error":false,
      "errorMessages":[

      ],
      "timestamp":1625478455,
      "timezone":"europe\\/london",
      "timing":2.625,
      "rows":1
   },
   "payload": null
  }

Endpoint:

POST apiUrl/v2/job/cancel/{jobId}

Headers:

Authorization: Bearer {bearer_token}

Content-Type: application/json

When the call is made to apiUrl/v2/job/cancel/{jobId}, the L10 Delivery solution attempts to cancel a job that is not in a final state (completed, canceled). A job can be canceled up to EN ROUTE PICKUP.

Callbacks

Callback Payload

Job & Delivery Status

Callback Payload

[
  {
   "Id":"5054f27a-e1fc-11ea-8315-0a9ef8d0da5c",
   "ProviderTimestamp":1234123556,
   "SystemTimestamp":1597828438,
   "ClientRef":"24596234",
   "JobId":1,
   "QuoteId":0,
   "TaskId":1,
   "ItemId":0,
   "TotalPickupCount":0,
   "TotalDeliveryCount":0,
   "TransportType":"CAR",
   "JobStatus":"booked",
   "QuoteStatus":"",
   "QuotePrice":"",
   "QuotePriceCancelled":"",
   "QuoteProviderJobId":"",
   "DeliveryStatus":"pending",
   "TaskStatus":"",
   "Driver":{
      "Id":"",
      "Name":"",
      "Phone":"",
      "Image":""
   },
   "Vehicle":{
      "Id":"0",
      "Type":"",
      "Registration":"",
      "EnvironmentalImpact":"",
      "EngineType":""
   },
   "Location":{
      "Latitude":12.2345,
      "Longitude":32.7825767,
      "Speed":0,
      "Heading":0,
      "Accuracy":0,
      "Moving":false,
      "Altitude":0
   },
   "GeoFencing":{
      "PickupRadius":0,
      "DeliveryRadius":0,
      "PickupCount":0,
      "DeliveryCount":0,
      "PickupHasHit":false,
      "DeliveryHasHit":false
   },
   "Device":{
      "Name":"",
      "Identifier":"",
      "SignalNetworkType":"",
      "SignalStrength":0,
      "BatteryLevel":0,
      "PowerPlugged":false
   },
   "Timing":{
      "EstimatedPickup":1234123556,
      "EstimatedDelivery":1234123556,
      "PickupCount":0,
      "DeliveryCount":0,
      "EstimatedDelay":0
   },
   "Attachments":[
      {
         "Type":"SignatureData",
         "Name":"",
         "Data":[
            "base64;...."
         ]
      },
      {
         "Type":"PhotoData",
         "Name":"",
         "Data":[
            "base64;...."
         ]
      },
      {
         "Type":"AgeCheckData",
         "Name":"",
         "Data":[
            "base64;...."
         ]
      }
   ],
   "Origin":""
  }
]

If CallbackUrl is specified in either the quote or immediate booking request payload, the Client will be notified for status and or location updates (where possible), through callbacks to this URL.

Keys fields within the callback are the Job Status and the Delivery Status. The following table shows the range of values for both fields:

Job Status Delivery Status
acknowledged idle
pending idle
in_queue idle
pre_quote idle
quoted idle
booked idle, pending
in_progress driver_assigned, en_route_pickup, at_pickup, en_route_delivery, at_delivery, waiting
cancelled cancelled
expired cancelled
error error
rejected rejected
closed delivered

Postman project

To assist integrators the LineTen team has created a Postman project that contains example API calls that can be exchanged with our preproduction platform to generate real-time responses. Integrators can use the Postman project as a basis for validating their credentials, testing the different API calls and modeling different requests and configurations.

The Postman Windows client for X32 and X64 platforms is available from the Postman product website.

LineTen will supply the project file upon request or when this document is issued allowing us to include the client specific credentials into the project file to simplify their use.

Setup Guide

This section provides a short summary of the steps required to import the provided Postman project file and setup the application environment for use:

  1. Install and run the Postman application

  2. Import the supplied project file

  3. Once imported you will see an 'Nova L10 Delivery' package with an 'auth' folder containing example API calls relating to authorisation, and an 'L10 Delivery' folder containing example API calls for job quoting and booking

  4. The 'auth' API example will have been pre-setup with your pre-production credentials through the following Key/Value pairs in the 'Body':

    a. Key=client_id, Value=Your provided ID

    b. Key=client_secret, Value=Your provided secret

    c. Key=grant_type, Value=client_credentials

If the import was completed successfully then you should now be in a position to send the authorisation command and get a successful response, the access token from the response is automatically extracted and included in the other API requests (i.e. quote & book).

Included API Examples

The Postman project contains examples for the following:

ID Example Name Details
1 auth API call that completes and authorisation request using included credentials to obtain an access token that is included in the example L10 Delivery API calls
2 quote (client) API call to obtain a quote for a client delivery
3 quote (store) API call to obtain a quote for a store delivery.  The API request will need to contain a valid store identifier that matches a store setup on the pre-production server
4 book API call to book a job based on a previously received quote.  The JobId and QuoteId should be edited to contain the values previously received from a quote request
5 immediate booking API call to complete an immediate booking where the quote is obtained and booked in a single interaction with the L10 Delivery v2 API

With the examples provided you are able to complete an authorisation, obtain different types of quote, book a book and perform an immediate booking. By logging into the pre-production NOVA dashboard using your account credentials you will be able to see the job quotes and bookings as they appear within L10 Delivery.

FAQ

ID Question Answer
1 Does the API provide a way of getting updates on booked jobs other than through the callback function (i.e. a polling mechanism) that can also be used to query a job history? Currently no - but a delivery history and delivery status history endpoint should be available in the future. In the meantime the callback API is the available mechanism for receiving job updates in real time.
2 How do you specify quantity in the Package fields? Quantity is expressed by sending multiple elements within the ‘Items’ array as opposed to a single element with a quantity value
3 In Location fields the Geolocation is required, but we don’t have this information? This is required information. There are a number of address lookup services available that perform this function.
4 How does RequestedTime and RequestedWindow work? These values are only used where the Task type is “delivery”. If neither exist in the payload then only delivery providers that accept ASAP bookings will respond. If RequestedTime is sent then a +60 minutes delivery window is calculated. If RequestedWindow is sent then that is used regardless of whether RequestedTime is sent.

Contact Us