Urbantz API documentation (v2)

Download OpenAPI specification:Download

Introduction

About our APIs

Our resources are the first part of the URI and then eventually followed by some sub-resources (i.e. /users/timesheet) or actions (i.e. /task/{id}/discard). Those URIs are predictable and make use of the various HTTP verbs, such as GET, POST, PUT and DELETE. For more details about the REST specification, visit the dedicated Wikipedia page.

When an issue occurs, we will return standardized error codes, such as 401 (you did not authenticate), 400 (bad payload), 403 (requested action is not allowed), 404 (resource not found), and so on. If you want a list of the available HTTP status codes, please click here.

Our sole type of content is JSON. Please be sure to be able to process JSON responses when implementing our APIs in your programs. We also solely accept application/json as a Content-Type when sending us payloads.

Our documentation is written following the OAS 3.0.2 format. This allows you to download our YAML documentation and use it with other documentation generators, generate client SDKs to consume it, or even make your developer's life easier by giving them simply the file instead of having to navigate through a website. If you wish to learn more about the OAS format, please click here.

Pagination

Some of our endpoints implement pagination, which allows you to retrieve a limited number of results per query and navigate through these results using pages.

Introduction

In this section, we'll explain how pagination works in Urbantz APIs. Pagination is employed in endpoints that return lists of entities such as tasks, rounds, reservations, or announcements. This approach enhances efficiency by managing large datasets effectively.

How Pagination Works

When you make requests to endpoints that support pagination, the results are constrained to a specific page size. This page size is determined by the endpoint itself and the size of the retrieved data. To utilize pagination, you are required to include the page number with every request. Although the page size is optional, you can find information about the default value and maximum limit for each endpoint in their respective documentation.

Parameters

  • page: An integer indicating the page number to retrieve. The default value is 0.
  • pageSize: An integer representing the number of results to retrieve in a single request. Each endpoint has a default value and a predefined maximum limit.

To retrieve all results associated with a particular request, you need to increment the page number. If the number of results is fewer than the page size, it indicates that you've reached the last available page. Any page number beyond this limit will result in an empty array ([]) being returned. Make sure to consult the documentation for each specific endpoint to determine if it supports pagination. By following these guidelines, you can effectively implement pagination in Urbantz APIs and optimize the process of retrieving large sets of data.

Where to test endpoints

If you wish to dry-run the calls to our APIs, (i.e. to develop your integration to our APIs) without playing with live/real data, you are invited to use the sandbox endpoints. Those endpoints are the same as production ones, but the domain is different. Production data is made with domain api.urbantz.com, where sandbox uses the api.sandbox.urbantz.com domain.

Please note that the domains have independent credentials. This is useful if you mistakenly switched environments and went into production instead of sandbox.

If you have more questions

Feel free to contact our Support Team if any question remains after reading this documentation our looking up in our Help center.

Announcements

Announcements are the tasks and services you created - There is one for the tasks and services created using the Web interface, and one for each announce made using the APIs, FTP or file upload.

Retrieve announcements

Returns a list of announcements. By default, it will return the 10 announcements for today (UTC). If you provide the date query parameter, it will return announcements for that specific date instead. It is possible to get the next ones adding the 'page' parameter. Announcements with unplanned tasks will be returned regardless of the date provided.

An announcement is the action of sending tasks into the system by making an API call. Tasks will be routed within the system according to the flow configuration.

Authorizations:
PlatformKeyBasicAuth
query Parameters
date
string <date>
Example: date=2019-09-30

The date the announcement was received

page
number (Page)
Default: 0

The page index of the requested records

status
string
Enum: "SUCCESS" "FAILED" "IN_PROGRESS"
Example: status=IN_PROGRESS

The announcement's status

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a single announcement by id

Returns one single announcement by its ID that is attached to the platform you are querying with. An announcement is the action of sending tasks into the system by making an API call. Tasks will be routed within the system according to the flow configuration.

Authorizations:
PlatformKeyBasicAuth
path Parameters
id
required
string
Example: 4dfc181e09d4e5eb4d3463da

Id of the announcement

Responses

Response samples

Content type
application/json
{
  • "_id": "507f191e810c19729de860ea",
  • "name": "string",
  • "flux": "507f191e810c19729de860ea",
  • "endpoint": "507f191e810c19729de860ea",
  • "by": "507f191e810c19729de860ea",
  • "count": 0,
  • "updatedCount": 0,
  • "platform": "4D3F12345AAAF30B2DD1CCFB",
  • "mode": "FILE",
  • "targetFluxes": [
    ],
  • "status": "SUCCESS",
  • "start": "2019-03-13T12:34:56.012Z",
  • "end": "2019-03-13T12:34:56.012Z",
  • "isLocked": true,
  • "error": {
    },
  • "issues": {
    }
}

Attachments

Attachments are files attached to entities, such as documents on tasks.

Get attachment URI

This endpoint is for getting a URI that can be used to download an attachment for an entity.

The relative path for this can be found on the attachments/[attachment]/url value when retrieving an entity.

The API does not check for the existence of the attachment, but generates a signed URI to retrieve the attachment. This means that if you provide details for an attachment that does not exist, then you will still get a signed URI, but will not be able to retrieve the document.

Authorizations:
PlatformKeyBasicAuth
path Parameters
type
required
string
Enum: "platforms" "tasks"

The type of the entity that the attachment is on (plural form)

Use “platforms” to retrieve any image of the task (signature, failed delivery picture, etc..)

Use “tasks” to retrieve the delivery note of the task (pdf file)

id
required
string
Example: 5f9af3044f8cc32e047d83a7

The ID of the entity

key
required
string
Example: cd360c3e-b917-40b2-ad71-885413c98dd6.pdf

The key for the attachment

Responses

External Carrier

The External Carrier endpoints are dedicated to our standardized integration for carriers. This collection of endpoints allows them to update parts of a task, to make the communication with their systems as seamless as possible.

This allows various carriers to implement an integration with our services - This is an advantage for both Urbantz and the Third-party, as Urbantz can provide more delivery solutions to the customers, and the third-party can be suggested by Urbantz when a customer wishes to easily start delivering without having its own fleet. This is still a new feature and will be evolving in the future.

set External Tracking ID of a task (id)

This endpoint allows you to assign a External Tracking ID (i.e. a tracking number for your delivery company) to a task identified by its internal Identifier.

This is mandatory to assign an External Tracking ID to a task you wish to work with. The other External Carrier APIs base themselves on the External Tracking ID to modify the statuses of the task, such as marking them delivered, returned, or assigned to a driver of your Carrier Fleet.

Authorizations:
PlatformKeyBasicAuth
path Parameters
id
required
string (ID)
Example: 507f191e810c19729de860ea

The Urbantz internal task id

Request Body schema: application/json
extTrackId
required
string (ExtTrackId)

An external task identifier to use for mapping data between an external carrier and Urbantz

Responses

Request samples

Content type
application/json
{
  • "extTrackId": "ext-12345"
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

set External Tracking ID of a task (TaskId)

This endpoint allows you to assign a External Tracking ID (i.e. a tracking number for your delivery company) to a task identified by its TaskId.

This is mandatory to assign an External Tracking ID to a task you wish to work with. The other External Carrier APIs base themselves on the External Tracking ID to modify the statuses of the task, such as marking them delivered, returned, or assigned to a driver of your Carrier Fleet.

Authorizations:
PlatformKeyBasicAuth
path Parameters
taskId
required
string (TaskId)
Example: my-task-id

The taskId of the task

Request Body schema: application/json
extTrackId
required
string (ExtTrackId)

An external task identifier to use for mapping data between an external carrier and Urbantz

Responses

Request samples

Content type
application/json
{
  • "extTrackId": "ext-12345"
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

set task as ASSIGNED

This endpoint allows you to mark a task as assigned, which means a driver has been assigned to do this pickup or delivery.

Authorizations:
PlatformKeyBasicAuth
path Parameters
extTrackId
required
string (ExtTrackId)
Example: ext-12345

The extTrackId of the task

Request Body schema: application/json
updatedTime
string <date-time> (CarrierTaskStatusUpdatedTime)

The date-time of the operation in ISO date format

updateType
string (CarrierTaskStatusUpdateType)
Enum: "id" "barcode" "total"

Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all.

object

Specify the items that are pending.

object

Specify the items that have arrived. Only for tasks of type delivery

roundName
string

Specify the name of the round where the task is assigned

sequence
integer

Specify the sequence of the task in the round

Responses

Request samples

Content type
application/json
{
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "updateType": "barcode",
  • "pending": {
    },
  • "arrived": {
    },
  • "roundName": "R01",
  • "sequence": 1
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

set task as ONGOING

This endpoint allows you to mark a task as ongoing, which means a driver has collected the task and is on its way to the customer.

When calling this endpoint, at least one of the following actions must be provided:

  • departed (this is an object which allows you to tell which items have departed. If everything goes well, all the items should be in departed)
  • missing (this is an object which allows you to tell which items are missing for the delivery, i.e. cannot fit in the vehicle or not found at the depart point)
Authorizations:
PlatformKeyBasicAuth
path Parameters
extTrackId
required
string (ExtTrackId)
Example: ext-12345

The extTrackId of the task

Request Body schema: application/json
updatedTime
string <date-time> (CarrierTaskStatusUpdatedTime)

The date-time of the operation in ISO date format

updateType
string (CarrierTaskStatusUpdateType)
Enum: "id" "barcode" "total"

Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all.

object

Specify the items that are pending. Only for tasks of type pickup

object

Specify the items that are departed. Only for tasks of type delivery

object

Specify the items that are missing. Only for tasks of type delivery

Responses

Request samples

Content type
application/json
{
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "updateType": "barcode",
  • "pending": {
    },
  • "departed": {
    },
  • "missing": {
    }
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

set task as COMPLETED

This endpoint allows you to mark a task as completed, when the task has been completed by the driver.

Depending on the success of the delivery or pickup, there are four different possibilities:

  • Delivered (the customer got the package)
  • Not Delivered (the customer did not get the package)
  • Picked up (the package has been given to the driver)
  • Not Picked Up (the package haven't been given to the driver)

One of the following keys must be provided at least: delivered, notDelivered, pickedUp, notPickedUp

Authorizations:
PlatformKeyBasicAuth
path Parameters
extTrackId
required
string (ExtTrackId)
Example: ext-12345

The extTrackId of the task.

Request Body schema: application/json
updatedTime
string <date-time> (CarrierTaskStatusUpdatedTime)

The date-time of the operation in ISO date format

updateType
string (CarrierTaskStatusUpdateType)
Enum: "id" "barcode" "total"

Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all.

object

Specify the items that are delivered. Only for tasks of type delivery

object

Specify the items that are not delivered. Only for tasks of type delivery

object

Specify the items that are picked up. Only for tasks of type pickup

object

Specify the items that are not picked up. Only for tasks of type pickup

object (CarrierTaskStatusPosition)

Position of the driver at the moment of the task completion

collectedAmount
number (CollectedAmount) >= 0

The amount of money the driver collected while delivering the goods

object (Metadata)

A general-purpose mechanism to store additional data. At the task level, metadata can be made explicit with a base schema in order to push or capture information during the execution of the task. Ask for support if you believe this can enhance your use case. Note: New metadata are merged with the existing one when updating a task

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

set task as RETURNED

This endpoint allows you to mark a task as returned, when the task delivery was attempted multiple times and no more attempts will be made.

Example: the task will be sent back to the seller.

Authorizations:
PlatformKeyBasicAuth
path Parameters
extTrackId
required
string (ExtTrackId)
Example: ext-12345

The extTrackId of the task.

Request Body schema: application/json
updatedTime
string <date-time> (CarrierTaskStatusUpdatedTime)

The date-time of the operation in ISO date format

updateType
string (CarrierTaskStatusUpdateType)
Enum: "id" "barcode" "total"

Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all.

object

Specify the items that are returned

Responses

Request samples

Content type
application/json
{
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "updateType": "barcode",
  • "returned": {
    }
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

set task as REPLANNED

When a task delivery is failed, it is common to be able to replan the task for delivery, generally the next day.

This endpoint allows you to replan a task which is COMPLETED and with all the items set as notDelivered (not delivered) or notPickedUp (Not picked up).

The payload is a time window of when the delivery will be made to the final customer, using the ISO 8601 format.

Authorizations:
PlatformKeyBasicAuth
path Parameters
extTrackId
required
string (ExtTrackId)
Example: ext-12345

The extTrackId of the task.

Request Body schema: application/json
required
object (TimeWindow)

The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round

Responses

Request samples

Content type
application/json
{
  • "timeWindow": {
    }
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

set task as READY_TO_COLLECT

This endpoint allows you to mark a task as ready to collect

Authorizations:
PlatformKeyBasicAuth
path Parameters
extTrackId
required
string (ExtTrackId)
Example: ext-12345

The extTrackId of the task.

Request Body schema: application/json
updatedTime
string <date-time> (CarrierTaskStatusUpdatedTime)

The date-time of the operation in ISO date format

updateType
string (CarrierTaskStatusUpdateType)
Enum: "id" "barcode" "total"

Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all.

object

Specify the items that are dropped.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

schedule a task

This endpoint allows to schedule a task that hasn't been started yet (this means with progress ANNOUNCED, ERROR, UNPLANNED, and GEOCODED)

Authorizations:
PlatformKeyBasicAuth
path Parameters
extTrackId
required
string (ExtTrackId)
Example: ext-12345

The extTrackId of the task.

Request Body schema: application/json
object

The time window during which the task should be completed.

excludeFromTimeslot
boolean
Default: false

If the task uses timeslots, send true to schedule the task out of the existing timeslots, so, the task won't be assigned to any timeslot and the capacity won't be decreased.

Responses

Request samples

Content type
application/json
{
  • "timeWindow": {
    },
  • "excludeFromTimeslot": false
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "string",
  • "initialSequence": 0,
  • "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
  • "extTrackId": "ext-12345",
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": false,
  • "actualTime": {
    },
  • "order": "5c98f80a6b3dc61664c05cbf",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "optimizationGroup": "string",
  • "optimizationCount": 0,
  • "replanned": false,
  • "sourceHash": "string",
  • "updated": "2019-03-24T12:34:56.123Z",
  • "when": "2019-03-24T12:34:56.123Z",
  • "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
  • "skills": [
    ],
  • "roundName": "R03",
  • "roundColor": "#FFCC0D",
  • "products": [
    ],
  • "hasRejectedProducts": false,
  • "activity": "classic",
  • "sequence": 1,
  • "id": "5c98f80a6b3dc61664c05cbb",
  • "flux": "5c3c63c23c32c30cb3cc1234c",
  • "collectedAmount": 10.2,
  • "closureDate": "2019-03-25T15:50:50.123Z",
  • "by": "5c3c63c23c32c30cb3cc1234c",
  • "attempts": 0,
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "announcement": "507f191e810c19729de860ea",
  • "shift": "string",
  • "serviceTime": 5,
  • "realServiceTime": {
    },
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "stopSequence": 2,
  • "date": "2019-03-13T12:34:56.012Z",
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "source": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "driver": "5c98f80a6b3dc61664c05cbb",
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "alerts": {
    },
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "010101_FR"
}

Update tracking information

This endpoint allows you to update the live tracking information for multiple tasks delivered in the same round.

Authorizations:
PlatformKeyBasicAuth
Request Body schema: application/json
when
required
string <date-time> <= 27 characters

The date and time when the location information was registered provided in ISO 8601 date format.

object

Driver location. This value is only accepted when the task is ONGOING.

required
Array of objects [ 1 .. 200 ] items

Tasks to update in batch. The maximum accepted is 200.

Responses

Request samples

Content type
application/json
{
  • "when": "2019-03-13T12:34:56Z",
  • "position": {
    },
  • "tasks": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Custom task update

This endpoint only works for platforms with a custom integration. It allows to update the following information of the task:

  • Time window
  • Task progress
  • Item status
  • Round name
  • Round sequence
  • ETA
  • Number of preceding tasks to be completed
  • Driver position
  • Failure reason
  • Signature
  • Success and failure pictures
  • Comments
  • Metadata
Authorizations:
PlatformKeyBasicAuth

Responses

Hubs

A Hub is the logistics center of a specific area from where the task is delivered to the end recipient. It usually represents a warehouse or a store depending of the business context.

Retrieve hubs

This endpoint fetches a paginated list of all the hubs your platform has access to. It also allows to filter the list by specific properties.

Authorizations:
PlatformKeyBasicAuth
query Parameters
page
number (Page)
Default: 0

The page index of the requested records

pageSize
number <= 500
Default: 100

The page size of the requested records

hubIds
Array of strings <= 100 items

The external hub identifiers to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Notifications

A notification is a communication sent to the recipient regarding the status of their task. It can be provided via email or SMS, depending on the configuration of your platform and the available contact information. Notifications can be automatically triggered by specific events or sent manually.

Retrieve notifications for a task

This endpoint fetches a list of all the notifications associated with a task.

Authorizations:
PlatformKeyBasicAuth
path Parameters
taskId
required
string
Example: 507f191e810c19729de860ea

The task id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Optimizer

The optimization endpoints allow you to trigger optimizations, without using the web interface.

Runs the optimizer

Runs the optimizer for all valid target flows

Authorizations:
PlatformKeyBasicAuth
query Parameters
targetFlux
required
string

A target flux is the combination of parameters allowing to isolate an optimisation problem. It is a key composed of:

  • hub
  • shift
  • flow
  • date

An independent optimization problem occurs at a hub, on a particular date, during a specific shift in a defined flow and using a specific optimisation.

Responses

Rounds

A round, also called mission, is a grouping of tasks with a determined sequence. This sequence is the order in which drivers should complete them to be most efficient based on criteria defined on the platform (duration, distance…).

Retrieve all rounds

Fetches a paginated list of all rounds on the authenticated platform. By default, the results displayed are date independent. To retrieve rounds of a specific day, use the date query parameter.

You are also able, with that endpoint, to filter rounds per hub, using the hub query parameter. If not specified, it will take all hubs into account.

Authorizations:
PlatformKeyBasicAuth
query Parameters
date
string <date>
Example: date=2019-03-19

Date of the round, format YYYY-MM-DD

page
number (Page)
Default: 0

The page index of the requested records

pageSize
number (PageSize)
Default: 10

The page size of the requested records

hub
string (ID)
Example: hub=507f191e810c19729de860ea

The internal hub identifier (Urbantz)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a specific round

Retrieves a specific round, based on its id. You can get this id by retrieving all rounds or via the web interface, when displaying a round's details, under the Identifier key of the General tab.

Authorizations:
PlatformKeyBasicAuth
path Parameters
id
required
string (ID)
Example: 507f191e810c19729de860ea

The task identifier

Responses

Response samples

Content type
application/json
{
  • "_id": "507f191e810c19729de860ea",
  • "realInfo": {
    },
  • "name": "string",
  • "status": "CREATED",
  • "activity": "classic",
  • "shift": "string",
  • "targetFlux": "string",
  • "platform": "507f191e810c19729de860ea",
  • "metadata": {
    },
  • "labelsAndSkills": [
    ],
  • "date": "2019-03-13T12:34:56.012Z",
  • "dimensions": {
    },
  • "hub": {
    },
  • "startTime": "2019-03-13T12:34:56.012Z",
  • "endTime": "2019-03-13T12:34:56.012Z",
  • "validated": true,
  • "totalViolationTime": 0,
  • "totalWaitTime": 0,
  • "totalDistance": 0,
  • "totalTravelTime": 0,
  • "totalBreakServiceTime": 0,
  • "totalOrderServiceTime": 0,
  • "totalTime": 0,
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "totalCost": 0,
  • "orderCount": 0,
  • "updated": "2019-03-13T12:34:56.012Z",
  • "reloads": [
    ],
  • "flux": "5c3c63f23b37f30c4fd0240e",
  • "id": "507f191e810c19729de860ea",
  • "orderDone": 0,
  • "senders": [
    ],
  • "picture": "string",
  • "driver": {
    },
  • "stops": [
    ],
  • "delay": {
    },
  • "vehicle": {
    }
}

Create preset rounds

This endpoint allows you to create rounds based on preset tasks. As a user, you are responsible to provide the exact information required for the round.

This is useful, when you have your own optimization system and you want the results of your optimization to be reflected in Urbantz.

To use it, you have to provide an ordered list of stops for the round.

Authorizations:
PlatformKeyBasicAuth
Request Body schema: application/json
Array
roundName
string <string>

The round name to create.

example: ROUND_01_AFTERNOON

date
string <date>

The day to create the round.

If omitted, the system will try to use the date given in startTime. When startTime is omitted, the system will try to use the date given for the arriveTime of the first stop. When stops arriveTime is omitted, the system will assume the current date. As a result, you can't create a round in the future if all these attributes are omitted.

example: 2021-02-14

startTime
string <date-time>

The start time of the round.

The value must be an ISO 8601 date time string.

This value can be omitted if endTime is not provided. When provided, the value must match the arriveTime of the first stop.

When omitted, the system will try to use the arriveTime of the first stop to define the startTime of the round. When stops arriveTime is omitted, the system will take the timeWindow start of the first stop to define the startTime of the round.

example: 2021-02-14T09:00:00.000Z

endTime
string <date-time>

The end time of the round.

The value must be an ISO 8601 date time string.

This value can be omitted if startTime is not provided. When provided, the value must match the arriveTime of the last stop.

When omitted, the system will try to use the arriveTime of the last stop to define the endTime of the round.

example: 2021-02-14T17:00:00.000Z

driver
string <string>

Use the externalId of the driver to assign them to the round.

This value is optional unless you use a stop of type custom to start or end the round. example: [email protected]

vehicle
string <string>

Use the vehicle name to assign a specific vehicle to the round.

This value is optional.

example: truck2people

hub
string <string>

Use externalId of the hub to attach the round to the specified hub.

This value is mandatory if you use a stop of type hub.

example: hub_1

Array of objects

The ordered list of stops to include in the round.

Responses