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.

Authentication

Urbantz offers two authentication methods: Basic auth with API key and oAuth2 / OpenId Connect.

To authenticate with API key, you need to copy the api key shown in Administration > Platform > General and include it in every request as username in the authorization header or use the header “x-api-key”.

To authenticate with OpenID, you need to create a client in Administration > Platform > General > Security and use the following URL to retrieve the temporary token

https://auth.urbantz.com/realms/{account_snake}-{account_type}/protocol/openid-connect/token being:

  1. account_snake the snake-case identifier used in the URL of your platform or sender portal.

  2. account_type the type of account. It can be “platform“ or “sender”.

Request

curl --location --request POST 'https://auth.urbantz.com/realms/my_account_name-platform/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{ CLIENT_ID }}' \
--data-urlencode 'client_secret={{ CLIENT_SECRET }}' \
--data-urlencode 'grant_type=client_credentials'

Response

{
    "access_token": {{ JWT_TOKEN }},
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "urbantz"
}

In the response you will find the access token and the expiration time:

  • access_token is the Bearer token that will be passed to the Urbantz API
  • expires_in indicates how long (in seconds) the token is valid (5 minutes).

The access token must be provided in every request using the authorization header.

Example

curl --location --request GET '{{ URBANTZ_API }}/v2/announcement' \
--header 'Authorization: Bearer {ACCESS_TOKEN}';

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

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

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Assign a driver to a round

Assigns a driver to a round

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

The round identifier

driverId
required
string
Example: contoso.jean_dupont.1

The external ID of the driver

Responses

Get real distance travelled

Get the real distance travelled by the driver during the round as calculated using GPS points collected while the driver is en route. This is only available after a round completes.

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

The round identifier

Responses

Response samples

Content type
application/json
{
  • "realDistanceInMeter": 0,
  • "confidenceLevel": "HIGH",
  • "when": "2019-03-13T12:34:56.012Z"
}

Get GHG

Get metrics about green house gases that were emitted during the round while the driver is en route. This is only available after a round completes.

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

The round identifier

Responses

Response samples

Content type
application/json
{
  • "totalCo2Emission": 0,
  • "totalDistanceInMeter": 0,
  • "distanceType": "REAL",
  • "vehicleType": "string",
  • "energyType": "string",
  • "when": "2019-03-13T12:34:56.012Z",
  • "roundStartDate": "2019-03-13T12:34:56.012Z",
  • "roundEndDate": "2019-03-13T12:34:56.012Z",
  • "co2EmissionPerTask": [
    ]
}

Rename rounds

Rename rounds. Only 100 rounds can be updated per request.

Authorizations:
PlatformKeyBasicAuth
Request Body schema: application/json
Array
roundId
required
string

The round identifier.

name
required
string <= 15 characters

The new name that you want to assign to the round.

Not allowed to use names that are already in use by active rounds on the same platform when round numbering per hub is disabled.

Not allowed to use names that are already in use by active rounds of the same hub when round numbering for that hub is enabled.

Ongoing or completed rounds cannot be updated.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Shift rounds start time

Shift rounds start time. Only 100 rounds can be updated per request.

Authorizations:
PlatformKeyBasicAuth
Request Body schema: application/json
Array
roundId
required
string

The round identifier.

startTime
required
string <date>

The new start time that you want to assign to the round.

The round start time can be updated multiple times.

The new start time cannot fall on or after the original start time (start time when round is created), both on the first and later shifts.

The new start time cannot fall more than 24 hours in the past compared to the moment the request is made.

The new start time must fall on the same day as the round deliveries unless "long services" is enabled for the platform.

Ongoing or completed rounds cannot be updated.

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Tasks

A task can either be a pickup, or a delivery. Each task has its own metadata, items, products, and so on. A group of one pickup task and one delivery task is called an Order.

Multiple tasks can be assigned to a Round to be picked up and/or delivered.

Retrieve all tasks

Retrieves a (paginated) list of all tasks for the platform.

You can combine query parameters in order to reduce the potential results.

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

The page index of the requested records

pageSize
number <= 500
Default: 10

The page size of the requested records. It has a limit of 500, i.e. if you provide a value greater than 500, maximum 500 records will be returned.

taskId
string

The external task id to search for

taskReference
string (TaskReference) <= 256 characters
Example: taskReference=task-ref-001-d

The secondary task id to search for

hub
string (ID)
Example: hub=507f191e810c19729de860ea

The ID of the hub to which the task has been assigned

date
string <date>
Example: date=2022-09-03

The date the task needs to be executed, in the format YYYY-MM-DD. If the unplanned parameter is sent with value true, the date parameter is ignored.

round
string (ID)
Example: round=507f191e810c19729de860ea

The round id to which the task was assigned

full
string

Full text search on contact details or address details

announcement
string (ID)
Example: announcement=507f191e810c19729de860ea

The announcement id associated with the tasks

unplanned
boolean

Get the tasks without date. It overrides the date parameter of the query.

progress
string (TaskProgress)
Enum: "ANNOUNCED" "ASSIGNED" "COMPLETED" "DISCARDED" "ERROR" "GEOCODED" "MISSING" "ONGOING" "READY_TO_COLLECT" "UNPLANNED"

Search based on progress of the task

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Announce new tasks

This endpoint allows you to announce tasks for execution by a platform you are entitled to use. As a task sender, you are configured to send tasks to one or more logistics or servicing platforms.

The announcement is an asynchronous process; If you wish to know what is the status of the announcement you made, you can query it using our retrieve announcements endpoint. You can also configure an endpoint to send a callback (webhook) once the announcement is completed.

For more information, please refer to the How to use WebHooks documentation section of this documentation.

Authorizations:
(PlatformKeyFlowKey) BasicAuth
Request Body schema: application/json
Array
type
string (TaskType)
Enum: "delivery" "pickup"

The type of task to be performed

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

Array of objects (AnnounceTaskProductsArray)

A list of products that the delivery will include

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

object (TaskNotificationSettings)

Notification settings for this task

carrier
string <= 128 characters

Identifier of the carrier to which the task will be associated. If the identifier is not valid, the task won't be associated to any carrier.

client
string

The value provided here will depend on the option selected in the flow configuration.

  • Option "Specific client": the field is not required, the configured sender will be used by default.
  • Option "Announced by name": the sender's full name is required. The name must be exactly the same as the one defined in the platform.
  • Option "Announced by code": the sender will be chosen based on the assigned code. The value must match exactly with one of the configured values.

If the value provided doesn't match any of the rules, the sender associated to the "secret" value provided in the headers will be used.

Important note: If the sender in the announcement does not match any of our record, then the sender associated to the "secret" value provided in the headers will be used.

collectedAmount
number >= 0

The amount of money the driver collected while delivering the goods

price
number >= 0
round
string
sequence
integer >= 1
instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

date
string <date-time>
serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

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

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

object (Contact)

Information of the recipient of the task

required
object (AnnouncedAddress)
Array of objects (AnnouncedItem)
object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

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

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object (Collect)

The click and collect information

timeslotReservationId
string (TimeslotReservationId)

Internal identifier to associate a task to a timeslot reservation

priority
number >= 0

Priority can influence the result optimization. In case not all of the tasks can fit in the round(s), the tasks with a higher priority are more likely to be included than the ones with lower priority. The higher the number, the higher the priority of the task will be.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "announcement": "string",
  • "received": 0,
  • "time": "2019-03-13T12:34:56.012Z"
}

Retrieve a specific task

Fetches information about a specific task, based on its internal identifier.

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

The task id

Responses

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Update a task (id)

Updates a task after it has been announced, based on its internal identifier.

It is not needed to send the complete task every time, only the fields that are to be updated. Items must be sent as a whole, therefore, all the properties of the items are required in each time an item is updated.

When providing items, it is possible to update or replace them. When updating the items, they will keep the history logs and the timeslot availability won't be recalculated (unless dimensions or labels are changed). When replacing them, the items will be reset, and the timeslot availability will be recalculated. To avoid replacing the items, it is required to provide _id.

Note that the update of some fields is only possible if the task has not already been assigned to a round. Some fields can no longer be updated once a task has its progress property set to COMPLETED.

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

The task internal identifier

Request Body schema: application/json
taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

paymentType
string
Enum: "CCOD" "COD" "(null value)"
skills
Array of strings (TaskSkills)

Skills the driver must have to execute the task. They are calculated from the items.

Array of objects (TaskProductsArray)

A list of products that the delivery will include

activity
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

sequence
integer >= 1
collectedAmount
number >= 0

The amount of money the driver collected while delivering the goods

serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

timeWindowMargin
number >= 0
Default: 0

A margin in minutes to the time window which is deemed acceptable

labels
Array of strings (TaskLabels)

Labels the vehicle must have to execute the task. They are calculated from the items.

instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

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

object (Dimensions)

An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated.

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

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

object (Contact)

Information of the recipient of the task

object (Address)

Geocoded address of the task

object (SourceAddress)

Address provided at announcement

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

price
number >= 0

The price of the task (basket price for e-commerce)

Array of objects (Item)
object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

object (TaskExecution)

Information collected by the driver during the execution of the task

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object (TaskNotificationSettings)

Notification settings for this task

object (Collect)

The click and collect information

Array of objects (TaskReturnedProductsArray)

An array containing a list of the returned products for this task

priority
number >= 0

Priority can influence the result optimization. In case not all of the tasks can fit in the round(s), the tasks with a higher priority are more likely to be included than the ones with lower priority. The higher the number, the higher the priority of the task will be.

brandingTemplate
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

recalculateServiceTime
boolean
Default: false

Recalculates service time based on preconfigured service time rules.

Responses

Request samples

Content type
application/json
{
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "paymentType": "CCOD",
  • "skills": [
    ],
  • "products": [
    ],
  • "activity": "string",
  • "sequence": 1,
  • "collectedAmount": 0,
  • "serviceTime": 5,
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "address": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "categories": [
    ],
  • "notificationSettings": {
    },
  • "collect": {
    },
  • "returnedProducts": [
    ],
  • "priority": 0,
  • "brandingTemplate": "string",
  • "recalculateServiceTime": false
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Update a task (TaskId)

Updates a task after it has been announced, based on its taskId. It requires the taskId to be unique, otherwise the update will be rejected.

It is not needed to send the complete task every time, only the fields that are to be updated. Items must be sent as a whole, therefore, all the properties of the items are required in each time an item is updated.

When providing items, it is possible to update or replace them. When updating the items, they will keep the history logs and the timeslot availability won't be recalculated (unless dimensions or labels are changed). When replacing them, the items will be reset, and the timeslot availability will be recalculated. To avoid replacing the items, it is required to provide _id.

Note that the update of some fields is only possible if the task has not already been assigned to a round. Some fields can no longer be updated once a task has its progress property set to COMPLETED.

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

The taskId

Request Body schema: application/json
taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

paymentType
string
Enum: "CCOD" "COD" "(null value)"
skills
Array of strings (TaskSkills)

Skills the driver must have to execute the task. They are calculated from the items.

Array of objects (TaskProductsArray)

A list of products that the delivery will include

activity
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

sequence
integer >= 1
collectedAmount
number >= 0

The amount of money the driver collected while delivering the goods

serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

timeWindowMargin
number >= 0
Default: 0

A margin in minutes to the time window which is deemed acceptable

labels
Array of strings (TaskLabels)

Labels the vehicle must have to execute the task. They are calculated from the items.

instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

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

object (Dimensions)

An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated.

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

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

object (Contact)

Information of the recipient of the task

object (Address)

Geocoded address of the task

object (SourceAddress)

Address provided at announcement

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

price
number >= 0

The price of the task (basket price for e-commerce)

Array of objects (Item)
object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

object (TaskExecution)

Information collected by the driver during the execution of the task

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object (TaskNotificationSettings)

Notification settings for this task

object (Collect)

The click and collect information

Array of objects (TaskReturnedProductsArray)

An array containing a list of the returned products for this task

priority
number >= 0

Priority can influence the result optimization. In case not all of the tasks can fit in the round(s), the tasks with a higher priority are more likely to be included than the ones with lower priority. The higher the number, the higher the priority of the task will be.

brandingTemplate
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

recalculateServiceTime
boolean
Default: false

Recalculates service time based on preconfigured service time rules.

Responses

Request samples

Content type
application/json
{
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "paymentType": "CCOD",
  • "skills": [
    ],
  • "products": [
    ],
  • "activity": "string",
  • "sequence": 1,
  • "collectedAmount": 0,
  • "serviceTime": 5,
  • "maxTransitTime": 0,
  • "timeWindowMargin": 0,
  • "labels": [
    ],
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "metadata": {
    },
  • "dimensions": {
    },
  • "timeWindow": {
    },
  • "timeWindow2": {
    },
  • "contact": {
    },
  • "location": {
    },
  • "address": {
    },
  • "hasBeenPaid": false,
  • "price": 0,
  • "items": [
    ],
  • "requires": {
    },
  • "execution": {
    },
  • "categories": [
    ],
  • "notificationSettings": {
    },
  • "collect": {
    },
  • "returnedProducts": [
    ],
  • "priority": 0,
  • "brandingTemplate": "string",
  • "recalculateServiceTime": false
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Discard a task (id)

Cancels a task execution, based on the task internal identifier. This requires the task to not be in a round yet. To force the discard if the task is in a round, please see the removeFromRound optional query parameter.

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

The database ID of the task to discard.

query Parameters
removeFromRound
boolean

Set to true if the task should be removed from its current round before being discarded. When set to false the API will reject requests to discard tasks that are assigned to a round. Defaults to false.

Responses

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Discard a task (TaskId)

Cancels a task execution, based on the TaskId. This requires the task to not be in a round yet. To force the discard if the task is in a round, please see the removeFromRound optional query parameter.

Please note that it requires the taskId to be the only one without a discarded status active. If multiple tasks have the same taskId for and aren't discarded or completed, this call will fail and tell you to use the ID as there is an ambiguity. A list of IDs will be given to you to compare the tasks having the same TaskId.

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

The taskId of the task to discard.

query Parameters
removeFromRound
boolean

Set to true if the task should be removed from its current round before being discarded. When set to false the API will reject requests to discard tasks that are assigned to a round. Defaults to false.

Responses

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Replan a task (id)

Replan the failed tasks to another day and time slot. The task must be COMPLETED, and all the items in it must be not delivered or not picked up.

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

The database ID the task to replan.

Request Body schema: application/json
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

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": {
    },
  • "timeWindow2": {
    }
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Replan a task (TaskId)

Replan the failed tasks to another day and time slot. The task must be COMPLETED, and all the items in it must be not delivered or not picked up.

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

The taskId of the task to replan.

Request Body schema: application/json
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

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": {
    },
  • "timeWindow2": {
    }
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Receive a task (id)

Put a task to receive

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

The database ID the task to receive.

Request Body schema: application/json
Array of objects

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string"
}

Retrieve tracking information

Fetches tracking information about a specific task, based on its internal identifier or its taskId.

The maximum number of requests for this endpoint is 3600 requests per minute.

Authorizations:
PlatformKeyBasicAuth
query Parameters
internalId
string (ID)
Example: internalId=507f191e810c19729de860ea

The tasks internal id to search for

taskId
string (TaskId)
Example: taskId=my-task-id

The taskId to search for

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Timeslot booking

Integrate the scheduling flow in your own online shop with 3 simple steps and connect with multiple carriers with one single and standard entry point.

This API allows to retrieve timeslots in a defined period from multiple carriers and hubs based on the rules previously defined in your platform.

Once a timeslot is selected, the API will communicate the reserved timeslot to the carrier and reserve it internally in Urbantz.

The last step is to confirm the timeslot. In this step the timeslot will be confirmed to the carrier .

Get timeslots

This API allows to retrieve the available timeslots from a specific hub and carrier. You can query for a maximum of 14 days in a single request.

All the data sent in this step will be stored and used in the following steps if it is required.

Authorizations:
(PlatformKeyFlowKeyOptional) BasicAuth
header Parameters
reference
string

Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs.

Request Body schema: application/json
hubId
string <= 255 characters

When using the API to consume timeslots from an external carrier, this field is optional unless stated otherwise by the carrier.

hubId is mandatory to retrieve timeslots created in Urbantz. hubId accepts the "Urbantz hub id" or the "external hub id". Both can be found in the hub configuration screen.

As an alternative, the hub can be selected automatically using the Hub Allocation Rules configured in the Flow. To use these rules, the flow secret must be provided in the request (see Authorization section).

carriers
Array of strings[ items <= 128 characters ]
start
required
string <date-time> <= 27 characters

Search for timeslots from the date defined in ISO 8601 format. A minimal precision to the minutes is required. Seconds and milliseconds can be omitted (they will default to 0).

stop
required
string <date-time> <= 27 characters

Search for timeslots until the date defined in ISO 8601 format. A minimal precision to the minutes is required. Seconds and milliseconds can be omitted (they will default to 0). The difference between start and stop cannot be more than 14 days.

serviceTime
number [ 0 .. 18000 ]

Amount of service time consumed in minutes for the timeslot.

taskId
string <= 256 characters
taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

type
string
Default: "delivery"
Enum: "delivery" "pickup"
required
object (address)
Array of objects (item) <= 1024 items
object (contact)
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
{
  • "hubId": "string",
  • "carriers": [
    ],
  • "start": "2021-03-30T09:00Z",
  • "stop": "2021-04-10T10:00Z",
  • "serviceTime": 18000,
  • "taskId": "string",
  • "taskReference": "task-ref-001-d",
  • "type": "delivery",
  • "address": {
    },
  • "items": [
    ],
  • "contact": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "timeslots": [
    ],
  • "recipientTimeZoneId": "Europe/Brussels"
}

Reserve a timeslot

This API allows to reserve a timeslot using the timeslot id received in Get timeslots.

The reservation will hold the capacity in the timeslot until it is cancelled or expired.

Once the reservation is confirmed the capacity will be blocked permanently.

Authorizations:
PlatformKeyBasicAuth
header Parameters
reference
string

Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs.

Request Body schema: application/json
timeslotId
required
string
confirm
boolean

When this parameter is true, the reservation will be autoconfirmed and it won’t be needed to use /confirm-reservation

ttl
number [ 5 .. 1440 ]
Default: 120

Time to live of the reservation. If the reservation is not confirmed within this time, it will be cancelled automatically. This value must be provided in minutes and allows a range between 5 minutes and 1440 minutes (24 hours). Default: 120. If a carrier has a hard time to live, the ttl field will be ignored

Responses

Request samples

Content type
application/json
{
  • "timeslotId": "string",
  • "confirm": true,
  • "ttl": 300
}

Response samples

Content type
application/json
{
  • "reservationId": "string",
  • "carrierReservationId": "string",
  • "isConfirmed": true,
  • "expires": "2023-10-13T05:02:56.148Z"
}

Confirm a reservation

This API allows to confirm an existing reservation. Only pending reservations can be confirmed, if the reservation was cancelled it won't be possible to confirm it.

The information sent in this step will be appended to the information sent in get timeslots. In case of data contradictions, the API will return an error.

Authorizations:
PlatformKeyBasicAuth
header Parameters
reference
string

Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs.

Request Body schema: application/json
reservationId
required
string <= 128 characters
taskId
string <= 256 characters
taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

serviceTime
number [ 0 .. 18000 ]

Amount of service time consumed in minutes for the timeslot.

type
string
Default: "delivery"
Enum: "delivery" "pickup"
object (address)
Array of objects (item) <= 1024 items
object (contact)
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
{
  • "reservationId": "string",
  • "taskId": "string",
  • "taskReference": "task-ref-001-d",
  • "serviceTime": 18000,
  • "type": "delivery",
  • "address": {
    },
  • "items": [
    ],
  • "contact": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{ }

Cancel a reservation

The API allows to cancel an existing reservation that wasn't previously cancelled or assigned.

Authorizations:
PlatformKeyBasicAuth
header Parameters
reference
string

Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs.

Request Body schema: application/json
reservationId
required
string <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "reservationId": "string"
}

Response samples

Content type
application/json
{ }

Retrieve reservation (id)

The API allows to get an existing reservation by its id

Authorizations:
PlatformKeyBasicAuth
path Parameters
reservationId
required
string

Use this parameter to pass the id of the reservation.

Responses

Response samples

Content type
application/json
{
  • "internalReservationId": "6294ab89974c66bf1f8e0ad7",
  • "carrierReservationId": "983ba310-c375-4dc4-92fc-3c15813ee9aa",
  • "start": "2019-03-13T12:34:56.012Z",
  • "stop": "2019-03-20T12:34:56.012Z",
  • "hub": "string",
  • "status": "PENDING",
  • "task": "Task001",
  • "recipientTimeZoneId": "Europe/Brussels",
  • "expires": "2023-10-13T05:02:56.148Z",
  • "cancellationReason": "CANCELLED_BY_API"
}

Retrieve reservations

The API allows to get existing reservations by certain criterias.

Authorizations:
PlatformKeyBasicAuth
query Parameters
start
required
string <date-time>
Example: start=2019-03-13T12:34:56.012Z

The lower bound of the date range to search within. The search is based on the start date of the timeslots reserved. It should be provided in ISO (8601) date format.

stop
required
string <date-time>
Example: stop=2019-03-20T12:34:56.012Z

The upper bound of the date range to search within. The search is based on the start date of the timeslots reserved. It should be provided in ISO (8601) date format.

hubId
string (ID)
Example: hubId=507f191e810c19729de860ea

The (internal or external) ID of the hub to which the reservation has been assigned to.

status
string
Enum: "PENDING" "CONFIRMED" "ASSIGNED" "CANCELLED"
Example: status=PENDING

The status of the reservation.

carrier
string
Example: carrier=carrier-snake

The snake-case identifier of the carrier who has reserved the timeslot.

page
number (Page)
Default: 0

The page index of the requested records

pageSize
number
Default: 100

The page size of the requested records

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Tracking

Tracking endpoints provide the information needed to display a task to the end recipient. This includes information about the task itself, and configuration information around the task, such as theming and platform configurations.

Get task information

Get the information that is specific to a task and its end recipient.

Authorizations:
PlatformKeyBasicAuth
path Parameters
trackingId
required
string

Tracking identifier of the task

Responses

Response samples

Content type
application/json
{
  • "type": "delivery",
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "progress": "ANNOUNCED",
  • "status": "ARRIVED",
  • "arriveTime": "2019-03-25T15:50:50.123Z",
  • "serviceTime": 5,
  • "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
  • "collect": {
    },
  • "contact": {
    },
  • "timeWindow": {
    },
  • "location": {
    },
  • "driver": {
    },
  • "review": {
    },
  • "surveyAnswers": {
    },
  • "realTimeTracking": {
    }
}

Get the platform configurations of the task

Get the platform configuration information that is relevant for displaying a task to the end recipient. This includes configurations such as theming and rating preferences, for example.

Authorizations:
PlatformKeyBasicAuth
path Parameters
trackingId
required
string

Tracking identifier of the task

Responses

Response samples

Content type
application/json
{
  • "mapAvailability": 0,
  • "limitEtaToTimewindow": true,
  • "showDriver": true,
  • "showFailedDeliveryReason": true,
  • "showTasksBeforeMe": true,
  • "showLocationDetails": true,
  • "tasksBeforeMeThreshold": 0,
  • "timeDisplayMode": "TIME_WINDOW",
  • "theme": {
    },
  • "endpoint": {
    },
  • "surveyQuestions": [
    ],
  • "categoriesQuestions": {
    },
  • "failedReasons": [
    ],
  • "features": {
    },
  • "trustPilot": {
    },
  • "timeslots": [
    ],
  • "eta": {
    }
}

Get task information that changes frequently

Get information about a task's progress that are expected to change frequently.

Authorizations:
PlatformKeyBasicAuth
path Parameters
trackingId
required
string

Tracking identifier of the task

Responses

Response samples

Content type
application/json
{
  • "driverLocation": [
    ],
  • "precedingTasks": 0,
  • "eta": "1029-03-30T12:23:34.456Z"
}

Users

In Urbantz, a User is someone who can log-in to a given platform. The user has a role, and each role has a set of permissions.

For example, depending on the permissions, some users could not connect to the web interface, but could use the phone application.

Retrieve all users

Authorizations:
PlatformKeyBasicAuth
query Parameters
excludeUsersFromOtherPlatforms
boolean

If true, it returns only the users that belongs to this platform.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new user

When calling this endpoint, you will create a new user linked to the platform (or sender) you are representing (which is determined by checking your credentials).

Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.

Authorizations:
PlatformKeyBasicAuth
Request Body schema: application/json
email
required
string

The email address of the user. Needs to be unique globally in Urbantz

lastName
required
string
firstName
required
string
externalId
required
string

Your external identifier for this user. This must be unique for the whole platform.

password
string

The password needs to be at least 8 characters long, and include an upper and a lower case letter, and a number. If a custom password policy is enabled, the configured requirements will apply.

hubExternalId
string

the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information.

role
required
string
Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager"

The platform role identifier, as a string

sender
string

the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information.

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "lastName": "Dupont",
  • "firstName": "Jean",
  • "externalId": "jean_dupont",
  • "password": "Urbantz1",
  • "hubExternalId": "hub_1_kuopio",
  • "role": "Platform Cashier",
  • "sender": "my-sender-name"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Retrieve a specific user (id)

Retrieves a user, based on its internal identifier. The returned user is a basic version of the information we have.

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

The user identifier

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Update a specific user (id)

Update the information of a user, based on its internal identifier.

Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.

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

The user identifier

Request Body schema: application/json
firstName
string

The new First name of the user

lastName
string

The new Last name of the user

role
string
Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager"

The new role name of the user

hubExternalId
string

the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information.

sender
string

the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information.

Responses

Request samples

Content type
application/json
{
  • "firstName": "Jacques",
  • "lastName": "Brel",
  • "role": "Platform Manager",
  • "hubExternalId": "hub_1_helsinki",
  • "sender": "my-sender-name"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Ban a specific user (id)

Set a user as BANNED, based on its internal identifier. Banned users cannot log-in anymore to the services of Urbantz.

If you wish to re-enable a user, you can use the validate user (id) endpoint.

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

The user identifier

query Parameters
anonymize
boolean

The personal data of the user registered in your platform will be anonymized. All data that are anonymized cannot be recovered from Urbantz anymore. This action is definitive.

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Validate a specific user (id)

Set a user as VALIDATED, based on its internal identifier. Validated users are able to log-in to the services of Urbantz.

If you wish to block a user from using the Urbantz services, you can use the ban user (id) endpoint.

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

The user identifier

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Retrieve a specific user (email)

Retrieves a user, based on its email address. The returned user is a basic version of the information we have.

Authorizations:
PlatformKeyBasicAuth
path Parameters
email
required
string

The user email address

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Update a specific user (email)

Update the information of a user, based on its email address.

Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.

Authorizations:
PlatformKeyBasicAuth
path Parameters
email
required
string

The user email address

Request Body schema: application/json
firstName
string

The new First name of the user

lastName
string

The new Last name of the user

role
string
Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager"

The new role name of the user

hubExternalId
string

the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information.

sender
string

the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information.

Responses

Request samples

Content type
application/json
{
  • "firstName": "Jacques",
  • "lastName": "Brel",
  • "role": "Platform Manager",
  • "hubExternalId": "hub_1_helsinki",
  • "sender": "my-sender-name"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Ban a specific user (email)

Set a user as BANNED, based on its email address. Banned users cannot log-in anymore to the services of Urbantz.

If you wish to re-enable a user, you can use the validate user (email) endpoint.

Authorizations:
PlatformKeyBasicAuth
path Parameters
email
required
string

The user email address

query Parameters
anonymize
boolean

The personal data of the user registered in your platform will be anonymized. All data that are anonymized cannot be recovered from Urbantz anymore. This action is definitive.

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Validate a specific user (email)

Set a user as VALIDATED, based on its email address. Validated users are able to log-in to the services of Urbantz.

If you wish to block a user from using the Urbantz services, you can use the ban user (email) endpoint.

Authorizations:
PlatformKeyBasicAuth
path Parameters
email
required
string

The user email address

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Retrieve a specific user (ExternalId)

Retrieves a user, based on its External Identifier. The returned user is a basic version of the information we have.

Authorizations:
PlatformKeyBasicAuth
path Parameters
ref
required
string
Example: contoso.jean_dupont.1

The user external identifier

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Update a specific user (ExternalId)

Update the information of a user, based on its External Identifier.

Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.

Authorizations:
PlatformKeyBasicAuth
path Parameters
ref
required
string
Example: contoso.jean_dupont.1

The user external identifier

Request Body schema: application/json
firstName
string

The new First name of the user

lastName
string

The new Last name of the user

role
string
Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager"

The new role name of the user

hubExternalId
string

the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information.

sender
string

the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information.

Responses

Request samples

Content type
application/json
{
  • "firstName": "Jacques",
  • "lastName": "Brel",
  • "role": "Platform Manager",
  • "hubExternalId": "hub_1_helsinki",
  • "sender": "my-sender-name"
}

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Ban a specific user (ExternalId)

Set a user as BANNED, based on its External Identifier. Banned users cannot log-in anymore to the services of Urbantz.

If you wish to re-enable a user, you can use the validate user (ExternalId) endpoint.

Authorizations:
PlatformKeyBasicAuth
path Parameters
ref
required
string
Example: contoso.jean_dupont.1

The user external identifier

query Parameters
anonymize
boolean

The personal data of the user registered in your platform will be anonymized. All data that are anonymized cannot be recovered from Urbantz anymore. This action is definitive.

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Validate a specific user (ExternalId)

Set a user as VALIDATED, based on its External Identifier. Validated users are able to log-in to the services of Urbantz.

If you wish to block a user from using the Urbantz services, you can use the ban user (ExternalId) endpoint.

Authorizations:
PlatformKeyBasicAuth
path Parameters
ref
required
string
Example: contoso.jean_dupont.1

The user external identifier

Responses

Response samples

Content type
application/json
{
  • "id": "507f191e810c19729de860ea",
  • "hubExternalId": "hub_1_kuopio",
  • "email": "[email protected]",
  • "firstName": "John",
  • "lastName": "Doe",
  • "status": "VALIDATED",
  • "phoneNumber": "+1-202-555-0192",
  • "updated": "2019-03-13T12:34:56.012Z",
  • "when": "2019-03-13T12:34:56.012Z",
  • "external": false,
  • "role": "Platform Manager",
  • "externalId": "jon_doe_hub1"
}

Retrieve users' timesheets

Retrieves a list of all users with an existing timesheet, in addition of the basic information of each user.

Authorizations:
PlatformKeyBasicAuth
query Parameters
dateFrom
string <date-time>

A date used to filter from in the format YYYY-MM-DD

dateTo
string <date-time>

a date used to filter to in the format YYYY-MM-DD

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Vehicles

Vehicles are the mean of transport for your missions. A vehicle is part of a fleet, eventually.

Vehicles are used to calculate the cost, speed and efficiency of a delivery - we base ourselves on the various criteria of a Vehicle object to determine the best paths for your deliveries, pickups, and services.

Retrieve all vehicles

Retrieves a list of all the vehicles that have been defined in the current platform.

Information includes reloading, if breaks are allowed for the vehicle, dimensions allowed inside, the cost per kilometer, etc.

Authorizations:
PlatformKeyBasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve a specific vehicle

Retrieves a vehicle, based on its internal identifier.

The content is the same as for the Retrieve all vehicles endpoint, except this is not an array but directly the Vehicle object.

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

The vehicle id

Responses

Response samples

Content type
application/json
{
  • "_id": "507f191e810c19729de860ea",
  • "reloading": {
    },
  • "custom": false,
  • "breaks": false,
  • "platform": "507f191e810c19729de860ea",
  • "name": "Semi-truck MANN-CO",
  • "maxOrders": 100,
  • "orderByHour": 100,
  • "maxDuration": 1440,
  • "maxDistance": 1500,
  • "accelerationTime": 2,
  • "fixedCost": 1,
  • "costPerUnitTime": 1,
  • "costPerUnitDistance": 0,
  • "dimensions": {
    },
  • "__v": 0,
  • "labels": [
    ],
  • "type": "car"
}

Voice

Voice endpoints provide information about VoIP calls made by drivers to recipients using the Urbantz app.

Get voice log

This endpoint is for getting a list of all VoIP calls that occured for a specific task.

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

The task id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

WebHooks

A WebHook (in this category) is not a real endpoint on our APIs. This is just a reference point allowing you to see what is the payload your server will receive when the said WebHook event is fired.

For more information on how to use this section of the documentation, please read the How to use the WebHooks documentation category of the introduction.

Webhooks usage

This section is a collection of payloads we could send to your server. Those are not actual endpoints of our API. To get more information about what they are, and how to set them up in your platform, please visit our Help Center.

You can use this documentation to see the payload we send to your servers, as specified in the "Request body" part of the request. The type of WebHook is defined in the URI. For example, the event "Optimization complete" will be displayed as POST /OptimizationComplete in our API documentation.

Your server has to respond with a status code 200 (OK) to acknowledge the data has been received on your side. If any other code is sent, an error will be triggered and an email can be sent to an email address you specified in the WebHook setup.

OptimizationComplete

The OptimizationComplete event is triggered whenever an optimization is finished successfully. This WebHook event can be found in the WebHooks section of a Flow.

It will send you an array of Task basic details, including the round name and its ID, and the sequence of the task in the round. This is interesting for your programs if you have logic depending on the result of an optimization.

Request Body schema: application/json
Array
date
string <date-time>

The date of the task

driver
string

The driver internal identifier. To get more details on the user, you can use the Retrieve a specific user (id) endpoint.

eta
string <date-time>

The estimated date and time of arrival for this task, if the round has no delays.

id
string

The internal identifier of the task

latitude
number

The latitude of the pickup or delivery address

longitude
number

The longitude of the pickup or delivery address

round
string

The round ID, useful to get more information using for example the Retrieve a specific round endpoint.

roundName
string

The round's name in which the task is assigned

sequence
integer

The sequence number of this task, for the round it is assigned to

status
string (TaskStatus)
Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED"

Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage

taskId
string

The task-id of this task

updated
string <date-time>

The date of when the task was edited for the last time

Responses

Request samples

Content type
application/json
[
  • {
    }
]

TaskChanged

The TaskChanged event is triggered whenever a task is modified. This WebHook event can be found in the WebHooks section of a Flow.

When that event occurs, the system will send you the task that was edited, taking into account the modifications that were applied by the editing. This event can be sent at the same time as TaskStatusChanged if the editing is a status transition.

Note: To avoid sending a large number of webhooks simultaneously this webhook will not be sent when using the global optimizer (from the announcements page). Please use OptimizationComplete instead.

Request Body schema: application/json
Array
object (UserSummaryExternal)

The user object. Present when the task was manually created by a user, null otherwise

__v
number
Deprecated

For internal use only. This field will be removed after January 1st, 2025.

_id
string (InternalTaskID)

Internal ID of the task. You should use this identifier for other API calls.

initialSequence
number

This represents the initial sequence number of the task, defined by the optimizer, before it was modified

trackingId
string (TrackingId)

The tracking identifier for this task. You need to add the urbantz domain in front of it. For example, in production the URI would look like https://web.urbantz.com/portal/tracking/insert-tracking-id-here.

extTrackId
string (ExtTrackId)

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

type
string (TaskType)
Enum: "delivery" "pickup"

The type of task to be performed

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

progress
string (TaskProgress)
Enum: "ANNOUNCED" "ASSIGNED" "COMPLETED" "DISCARDED" "ERROR" "GEOCODED" "MISSING" "ONGOING" "READY_TO_COLLECT" "UNPLANNED"

Represents the high-level stage of the task. Follows a general sequence as the task moves through its lifecycle

status
string (TaskStatus)
Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED"

Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage

Array of objects (Item)

The content of the task to be picked up or delivered.

client
string (ClientID)

The sender identifier

hub
string (HubID)

The hub identifier

hubName
string

The hub name

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

dependency
string

the identifier of a pickup task on which our task depends on (in case of a delivery task)

hasDependency
string

the identifier of a delivery task who depends on this task (in case of a pickup task)

round
string (RoundID)

The round identifier. It is only present after the task has been optimized.

archived
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

object (TaskActualTime)

It contains information of the time and place where the driver started executing the task. This information is only present if the Onsite feature is enabled

order
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

paymentType
string
Enum: "CCOD" "COD" "(null value)"

The kind of payment used: Cash on Delivery (COD), Credit Card on Delivery (CCOD) or null

platform
string

The platform identifier

platformName
string

The platform name

endpoint
string

The identifier of the flow in which the task was announced

object
Array of objects

The list of calls recorded by the driver

Array of objects

Issues occurred during the announcement of the task

Array of objects

List of manual SMS notifications sent to the recipient

object (TaskNotificationSettings)

Notification settings for this task

replanned
boolean
sourceHash
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

updated
string <date-time>

When the task was updated the last time (in ISO 8601 format)

when
string <date-time> (TaskWhen)

When the task was created (in ISO 8601 format)

targetFlux
string

A targetFlux (hub-shift-flux-date combination) representing an independent optimization problem

skills
Array of strings (TaskSkills)

Skills the driver must have to execute the task. They are calculated from the items.

roundName
string (RoundName)

Specify the name of the round where the task is assigned. It is only present after the task has been optimized.

roundColor
string

The round color, in hexadecimal, including the hash

Array of objects (TaskProductsArray)

A list of products that the delivery will include

hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

sequence
integer (TaskSequence) >= 1

Specifies the sequence of the task in the round. It is only present after the task has been optimized

id
string

The id of the task. If _id is provided, their value is shared.

flux
string (TaskFlux)

The identifier of the optimization configured used to optimize the task

collectedAmount
number (CollectedAmount) >= 0

The amount of money the driver collected while delivering the goods

closureDate
string <date-time> (ClosureDate)

The date and time the task was completed (in ISO 8601 format)

by
string (TaskSender)

The sender name

attempts
integer >= 0

The number of delivery attempts done

arriveTime
string <date-time> (TaskArrivalTime)

The estimated time of arrival to the delivery location (in ISO 8601 format)

announcement
string (AnnouncementID)

The identifier of the announcement

shift
string <= 32 characters

The name of the shift the task was assigned to

serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

object (RealServiceTime)

It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed.

imagePath
string

The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature.

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

timeWindowMargin
number >= 0
Default: 0

A margin in minutes to the time window which is deemed acceptable

stopSequence
number

The stop sequence number for this task, in the related round.

date
string <date-time>
Deprecated

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD. This field will be removed after January 1st, 2025.

labels
Array of strings (TaskLabels)

Labels the vehicle must have to execute the task. They are calculated from the items.

instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

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

object (Dimensions)

An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated.

object

The time window during which the task should be completed. It cannot be modified once the task is assigned to a round.

object

A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round.

object (Contact)

Information of the recipient of the task

object (Address)

Geocoded address of the task

object (SourceAddress)

Address provided at announcement

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

price
number >= 0

The price of the task (basket price for e-commerce)

driver
string

The identifier of the driver (urbantz user)

object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

object (TaskExecution)

Information collected by the driver during the execution of the task

Array of objects (TaskLog)

Log of the progress transition of the task

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object

Information about contactless delivery

object

If there are assets to picked up or to be left at the client

Array of objects

List of file attachments (pictures, delivery notes, etc...)

brandingTemplate
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

TaskStatusChanged

The TaskStatusChanged event is triggered whenever a task has its status transiting from one to another. This WebHook event can be found in the WebHooks section of a Flow.

When that event occurs, the system will send you the task that got the status changed. This event can be sent at the same time as TaskChanged as a status transition requires to modify the task.

Note: To avoid sending a large number of webhooks simultaneously this webhook will not be sent when using the global optimizer (from the announcements page). Please use OptimizationComplete instead.

Request Body schema: application/json
object (UserSummaryExternal)

The user object. Present when the task was manually created by a user, null otherwise

__v
number
Deprecated

For internal use only. This field will be removed after January 1st, 2025.

_id
string (InternalTaskID)

Internal ID of the task. You should use this identifier for other API calls.

initialSequence
number

This represents the initial sequence number of the task, defined by the optimizer, before it was modified

trackingId
string (TrackingId)

The tracking identifier for this task. You need to add the urbantz domain in front of it. For example, in production the URI would look like https://web.urbantz.com/portal/tracking/insert-tracking-id-here.

extTrackId
string (ExtTrackId)

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

type
string (TaskType)
Enum: "delivery" "pickup"

The type of task to be performed

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

progress
string (TaskProgress)
Enum: "ANNOUNCED" "ASSIGNED" "COMPLETED" "DISCARDED" "ERROR" "GEOCODED" "MISSING" "ONGOING" "READY_TO_COLLECT" "UNPLANNED"

Represents the high-level stage of the task. Follows a general sequence as the task moves through its lifecycle

status
string (TaskStatus)
Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED"

Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage

Array of objects (Item)

The content of the task to be picked up or delivered.

client
string (ClientID)

The sender identifier

hub
string (HubID)

The hub identifier

hubName
string

The hub name

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

dependency
string

the identifier of a pickup task on which our task depends on (in case of a delivery task)

hasDependency
string

the identifier of a delivery task who depends on this task (in case of a pickup task)

round
string (RoundID)

The round identifier. It is only present after the task has been optimized.

archived
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

object (TaskActualTime)

It contains information of the time and place where the driver started executing the task. This information is only present if the Onsite feature is enabled

order
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

paymentType
string
Enum: "CCOD" "COD" "(null value)"

The kind of payment used: Cash on Delivery (COD), Credit Card on Delivery (CCOD) or null

platform
string

The platform identifier

platformName
string

The platform name

endpoint
string

The identifier of the flow in which the task was announced

object
Array of objects

The list of calls recorded by the driver

Array of objects

Issues occurred during the announcement of the task

Array of objects

List of manual SMS notifications sent to the recipient

object (TaskNotificationSettings)

Notification settings for this task

replanned
boolean
sourceHash
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

updated
string <date-time>

When the task was updated the last time (in ISO 8601 format)

when
string <date-time> (TaskWhen)

When the task was created (in ISO 8601 format)

targetFlux
string

A targetFlux (hub-shift-flux-date combination) representing an independent optimization problem

skills
Array of strings (TaskSkills)

Skills the driver must have to execute the task. They are calculated from the items.

roundName
string (RoundName)

Specify the name of the round where the task is assigned. It is only present after the task has been optimized.

roundColor
string

The round color, in hexadecimal, including the hash

Array of objects (TaskProductsArray)

A list of products that the delivery will include

hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

sequence
integer (TaskSequence) >= 1

Specifies the sequence of the task in the round. It is only present after the task has been optimized

id
string

The id of the task. If _id is provided, their value is shared.

flux
string (TaskFlux)

The identifier of the optimization configured used to optimize the task

collectedAmount
number (CollectedAmount) >= 0

The amount of money the driver collected while delivering the goods

closureDate
string <date-time> (ClosureDate)

The date and time the task was completed (in ISO 8601 format)

by
string (TaskSender)

The sender name

attempts
integer >= 0

The number of delivery attempts done

arriveTime
string <date-time> (TaskArrivalTime)

The estimated time of arrival to the delivery location (in ISO 8601 format)

announcement
string (AnnouncementID)

The identifier of the announcement

shift
string <= 32 characters

The name of the shift the task was assigned to

serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

object (RealServiceTime)

It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed.

imagePath
string

The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature.

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

timeWindowMargin
number >= 0
Default: 0

A margin in minutes to the time window which is deemed acceptable

stopSequence
number

The stop sequence number for this task, in the related round.

date
string <date-time>
Deprecated

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD. This field will be removed after January 1st, 2025.

labels
Array of strings (TaskLabels)

Labels the vehicle must have to execute the task. They are calculated from the items.

instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

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

object (Dimensions)

An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated.

object

The time window during which the task should be completed. It cannot be modified once the task is assigned to a round.

object

A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round.

object (Contact)

Information of the recipient of the task

object (Address)

Geocoded address of the task

object (SourceAddress)

Address provided at announcement

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

price
number >= 0

The price of the task (basket price for e-commerce)

driver
string

The identifier of the driver (urbantz user)

object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

object (TaskExecution)

Information collected by the driver during the execution of the task

Array of objects (TaskLog)

Log of the progress transition of the task

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object

Information about contactless delivery

object

If there are assets to picked up or to be left at the client

Array of objects

List of file attachments (pictures, delivery notes, etc...)

brandingTemplate
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

timestamp
string <date-time>

The date when the webhook was sent to your server

Responses

Request samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string",
  • "timestamp": "2019-04-01T08:31:05.121Z"
}

TasksAnnounced

The TasksAnnounced event is triggered when a new announcement is sent to Urbantz, either from a file upload, FTP upload, web, or API call. This WebHook can be found in the WebHooks tab of a Flow.

The system will return an array containing a detailed list of Tasks that were included in that announcement. If the announcement has been made in the web or via file upload, the createdBy key of each task will contain the basic information of the user at the origin of that announce.

Request Body schema: application/json
Array
object (UserSummaryExternal)

The user object. Present when the task was manually created by a user, null otherwise

__v
number
Deprecated

For internal use only. This field will be removed after January 1st, 2025.

_id
string (InternalTaskID)

Internal ID of the task. You should use this identifier for other API calls.

initialSequence
number

This represents the initial sequence number of the task, defined by the optimizer, before it was modified

trackingId
string (TrackingId)

The tracking identifier for this task. You need to add the urbantz domain in front of it. For example, in production the URI would look like https://web.urbantz.com/portal/tracking/insert-tracking-id-here.

extTrackId
string (ExtTrackId)

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

type
string (TaskType)
Enum: "delivery" "pickup"

The type of task to be performed

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

progress
string (TaskProgress)
Enum: "ANNOUNCED" "ASSIGNED" "COMPLETED" "DISCARDED" "ERROR" "GEOCODED" "MISSING" "ONGOING" "READY_TO_COLLECT" "UNPLANNED"

Represents the high-level stage of the task. Follows a general sequence as the task moves through its lifecycle

status
string (TaskStatus)
Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED"

Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage

Array of objects (Item)

The content of the task to be picked up or delivered.

client
string (ClientID)

The sender identifier

hub
string (HubID)

The hub identifier

hubName
string

The hub name

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

dependency
string

the identifier of a pickup task on which our task depends on (in case of a delivery task)

hasDependency
string

the identifier of a delivery task who depends on this task (in case of a pickup task)

round
string (RoundID)

The round identifier. It is only present after the task has been optimized.

archived
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

object (TaskActualTime)

It contains information of the time and place where the driver started executing the task. This information is only present if the Onsite feature is enabled

order
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

paymentType
string
Enum: "CCOD" "COD" "(null value)"

The kind of payment used: Cash on Delivery (COD), Credit Card on Delivery (CCOD) or null

platform
string

The platform identifier

platformName
string

The platform name

endpoint
string

The identifier of the flow in which the task was announced

object
Array of objects

The list of calls recorded by the driver

Array of objects

Issues occurred during the announcement of the task

Array of objects

List of manual SMS notifications sent to the recipient

object (TaskNotificationSettings)

Notification settings for this task

replanned
boolean
sourceHash
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

updated
string <date-time>

When the task was updated the last time (in ISO 8601 format)

when
string <date-time> (TaskWhen)

When the task was created (in ISO 8601 format)

targetFlux
string

A targetFlux (hub-shift-flux-date combination) representing an independent optimization problem

skills
Array of strings (TaskSkills)

Skills the driver must have to execute the task. They are calculated from the items.

roundName
string (RoundName)

Specify the name of the round where the task is assigned. It is only present after the task has been optimized.

roundColor
string

The round color, in hexadecimal, including the hash

Array of objects (TaskProductsArray)

A list of products that the delivery will include

hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

sequence
integer (TaskSequence) >= 1

Specifies the sequence of the task in the round. It is only present after the task has been optimized

id
string

The id of the task. If _id is provided, their value is shared.

flux
string (TaskFlux)

The identifier of the optimization configured used to optimize the task

collectedAmount
number (CollectedAmount) >= 0

The amount of money the driver collected while delivering the goods

closureDate
string <date-time> (ClosureDate)

The date and time the task was completed (in ISO 8601 format)

by
string (TaskSender)

The sender name

attempts
integer >= 0

The number of delivery attempts done

arriveTime
string <date-time> (TaskArrivalTime)

The estimated time of arrival to the delivery location (in ISO 8601 format)

announcement
string (AnnouncementID)

The identifier of the announcement

shift
string <= 32 characters

The name of the shift the task was assigned to

serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

object (RealServiceTime)

It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed.

imagePath
string

The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature.

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

timeWindowMargin
number >= 0
Default: 0

A margin in minutes to the time window which is deemed acceptable

stopSequence
number

The stop sequence number for this task, in the related round.

date
string <date-time>
Deprecated

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD. This field will be removed after January 1st, 2025.

labels
Array of strings (TaskLabels)

Labels the vehicle must have to execute the task. They are calculated from the items.

instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

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

object (Dimensions)

An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated.

object

The time window during which the task should be completed. It cannot be modified once the task is assigned to a round.

object

A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round.

object (Contact)

Information of the recipient of the task

object (Address)

Geocoded address of the task

object (SourceAddress)

Address provided at announcement

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

price
number >= 0

The price of the task (basket price for e-commerce)

driver
string

The identifier of the driver (urbantz user)

object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

object (TaskExecution)

Information collected by the driver during the execution of the task

Array of objects (TaskLog)

Log of the progress transition of the task

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object

Information about contactless delivery

object

If there are assets to picked up or to be left at the client

Array of objects

List of file attachments (pictures, delivery notes, etc...)

brandingTemplate
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

TaskAssociated

The TaskAssociated event is triggered whenever a task has been associated to your platform. This webhook event can be configured in the Webhooks section of the Associates screen.

Request Body schema: application/json
Array
object (UserSummaryExternal)

The user object. Present when the task was manually created by a user, null otherwise

__v
number
Deprecated

For internal use only. This field will be removed after January 1st, 2025.

_id
string (InternalTaskID)

Internal ID of the task. You should use this identifier for other API calls.

initialSequence
number

This represents the initial sequence number of the task, defined by the optimizer, before it was modified

trackingId
string (TrackingId)

The tracking identifier for this task. You need to add the urbantz domain in front of it. For example, in production the URI would look like https://web.urbantz.com/portal/tracking/insert-tracking-id-here.

extTrackId
string (ExtTrackId)

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

type
string (TaskType)
Enum: "delivery" "pickup"

The type of task to be performed

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

progress
string (TaskProgress)
Enum: "ANNOUNCED" "ASSIGNED" "COMPLETED" "DISCARDED" "ERROR" "GEOCODED" "MISSING" "ONGOING" "READY_TO_COLLECT" "UNPLANNED"

Represents the high-level stage of the task. Follows a general sequence as the task moves through its lifecycle

status
string (TaskStatus)
Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED"

Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage

Array of objects (Item)

The content of the task to be picked up or delivered.

client
string (ClientID)

The sender identifier

hub
string (HubID)

The hub identifier

hubName
string

The hub name

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

dependency
string

the identifier of a pickup task on which our task depends on (in case of a delivery task)

hasDependency
string

the identifier of a delivery task who depends on this task (in case of a pickup task)

round
string (RoundID)

The round identifier. It is only present after the task has been optimized.

archived
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

object (TaskActualTime)

It contains information of the time and place where the driver started executing the task. This information is only present if the Onsite feature is enabled

order
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

paymentType
string
Enum: "CCOD" "COD" "(null value)"

The kind of payment used: Cash on Delivery (COD), Credit Card on Delivery (CCOD) or null

platform
string

The platform identifier

platformName
string

The platform name

endpoint
string

The identifier of the flow in which the task was announced

object
Array of objects

The list of calls recorded by the driver

Array of objects

Issues occurred during the announcement of the task

Array of objects

List of manual SMS notifications sent to the recipient

object (TaskNotificationSettings)

Notification settings for this task

replanned
boolean
sourceHash
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

updated
string <date-time>

When the task was updated the last time (in ISO 8601 format)

when
string <date-time> (TaskWhen)

When the task was created (in ISO 8601 format)

targetFlux
string

A targetFlux (hub-shift-flux-date combination) representing an independent optimization problem

skills
Array of strings (TaskSkills)

Skills the driver must have to execute the task. They are calculated from the items.

roundName
string (RoundName)

Specify the name of the round where the task is assigned. It is only present after the task has been optimized.

roundColor
string

The round color, in hexadecimal, including the hash

Array of objects (TaskProductsArray)

A list of products that the delivery will include

hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

sequence
integer (TaskSequence) >= 1

Specifies the sequence of the task in the round. It is only present after the task has been optimized

id
string

The id of the task. If _id is provided, their value is shared.

flux
string (TaskFlux)

The identifier of the optimization configured used to optimize the task

collectedAmount
number (CollectedAmount) >= 0

The amount of money the driver collected while delivering the goods

closureDate
string <date-time> (ClosureDate)

The date and time the task was completed (in ISO 8601 format)

by
string (TaskSender)

The sender name

attempts
integer >= 0

The number of delivery attempts done

arriveTime
string <date-time> (TaskArrivalTime)

The estimated time of arrival to the delivery location (in ISO 8601 format)

announcement
string (AnnouncementID)

The identifier of the announcement

shift
string <= 32 characters

The name of the shift the task was assigned to

serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

object (RealServiceTime)

It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed.

imagePath
string

The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature.

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

timeWindowMargin
number >= 0
Default: 0

A margin in minutes to the time window which is deemed acceptable

stopSequence
number

The stop sequence number for this task, in the related round.

date
string <date-time>
Deprecated

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD. This field will be removed after January 1st, 2025.

labels
Array of strings (TaskLabels)

Labels the vehicle must have to execute the task. They are calculated from the items.

instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

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

object (Dimensions)

An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated.

object

The time window during which the task should be completed. It cannot be modified once the task is assigned to a round.

object

A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round.

object (Contact)

Information of the recipient of the task

object (Address)

Geocoded address of the task

object (SourceAddress)

Address provided at announcement

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

price
number >= 0

The price of the task (basket price for e-commerce)

driver
string

The identifier of the driver (urbantz user)

object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

object (TaskExecution)

Information collected by the driver during the execution of the task

Array of objects (TaskLog)

Log of the progress transition of the task

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object

Information about contactless delivery

object

If there are assets to picked up or to be left at the client

Array of objects

List of file attachments (pictures, delivery notes, etc...)

brandingTemplate
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

timestamp
string <date-time>

The date when the webhook was sent to your server

Responses

Request samples

Content type
application/json
[
  • {
    }
]

TaskUnassociated

The TaskUnassociated event is triggered whenever another platform has unassociated a task from your platform. This webhook event can be configured in the Webhooks section of the Associates screen.

Request Body schema: application/json
object (UserSummaryExternal)

The user object. Present when the task was manually created by a user, null otherwise

__v
number
Deprecated

For internal use only. This field will be removed after January 1st, 2025.

_id
string (InternalTaskID)

Internal ID of the task. You should use this identifier for other API calls.

initialSequence
number

This represents the initial sequence number of the task, defined by the optimizer, before it was modified

trackingId
string (TrackingId)

The tracking identifier for this task. You need to add the urbantz domain in front of it. For example, in production the URI would look like https://web.urbantz.com/portal/tracking/insert-tracking-id-here.

extTrackId
string (ExtTrackId)

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

type
string (TaskType)
Enum: "delivery" "pickup"

The type of task to be performed

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

taskReference
string (TaskReference) <= 256 characters

A secondary task identifier to use for mapping data between systems.

progress
string (TaskProgress)
Enum: "ANNOUNCED" "ASSIGNED" "COMPLETED" "DISCARDED" "ERROR" "GEOCODED" "MISSING" "ONGOING" "READY_TO_COLLECT" "UNPLANNED"

Represents the high-level stage of the task. Follows a general sequence as the task moves through its lifecycle

status
string (TaskStatus)
Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED"

Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage

Array of objects (Item)

The content of the task to be picked up or delivered.

client
string (ClientID)

The sender identifier

hub
string (HubID)

The hub identifier

hubName
string

The hub name

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

dependency
string

the identifier of a pickup task on which our task depends on (in case of a delivery task)

hasDependency
string

the identifier of a delivery task who depends on this task (in case of a pickup task)

round
string (RoundID)

The round identifier. It is only present after the task has been optimized.

archived
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

object (TaskActualTime)

It contains information of the time and place where the driver started executing the task. This information is only present if the Onsite feature is enabled

order
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

paymentType
string
Enum: "CCOD" "COD" "(null value)"

The kind of payment used: Cash on Delivery (COD), Credit Card on Delivery (CCOD) or null

platform
string

The platform identifier

platformName
string

The platform name

endpoint
string

The identifier of the flow in which the task was announced

object
Array of objects

The list of calls recorded by the driver

Array of objects

Issues occurred during the announcement of the task

Array of objects

List of manual SMS notifications sent to the recipient

object (TaskNotificationSettings)

Notification settings for this task

replanned
boolean
sourceHash
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

updated
string <date-time>

When the task was updated the last time (in ISO 8601 format)

when
string <date-time> (TaskWhen)

When the task was created (in ISO 8601 format)

targetFlux
string

A targetFlux (hub-shift-flux-date combination) representing an independent optimization problem

skills
Array of strings (TaskSkills)

Skills the driver must have to execute the task. They are calculated from the items.

roundName
string (RoundName)

Specify the name of the round where the task is assigned. It is only present after the task has been optimized.

roundColor
string

The round color, in hexadecimal, including the hash

Array of objects (TaskProductsArray)

A list of products that the delivery will include

hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

sequence
integer (TaskSequence) >= 1

Specifies the sequence of the task in the round. It is only present after the task has been optimized

id
string

The id of the task. If _id is provided, their value is shared.

flux
string (TaskFlux)

The identifier of the optimization configured used to optimize the task

collectedAmount
number (CollectedAmount) >= 0

The amount of money the driver collected while delivering the goods

closureDate
string <date-time> (ClosureDate)

The date and time the task was completed (in ISO 8601 format)

by
string (TaskSender)

The sender name

attempts
integer >= 0

The number of delivery attempts done

arriveTime
string <date-time> (TaskArrivalTime)

The estimated time of arrival to the delivery location (in ISO 8601 format)

announcement
string (AnnouncementID)

The identifier of the announcement

shift
string <= 32 characters

The name of the shift the task was assigned to

serviceTime
integer (ServiceTime) [ 0 .. 18000 ]

The amount of time in minutes required to effectively complete the task. It cannot be modified once the task is assigned to a round

object (RealServiceTime)

It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed.

imagePath
string

The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature.

maxTransitTime
integer (MaxTransitTime) >= 0

The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery.

timeWindowMargin
number >= 0
Default: 0

A margin in minutes to the time window which is deemed acceptable

stopSequence
number

The stop sequence number for this task, in the related round.

date
string <date-time>
Deprecated

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD. This field will be removed after January 1st, 2025.

labels
Array of strings (TaskLabels)

Labels the vehicle must have to execute the task. They are calculated from the items.

instructions
string (Instructions) <= 1024 characters

Extra information for the driver to reach the destination

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

object (Dimensions)

An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated.

object

The time window during which the task should be completed. It cannot be modified once the task is assigned to a round.

object

A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round.

object (Contact)

Information of the recipient of the task

object (Address)

Geocoded address of the task

object (SourceAddress)

Address provided at announcement

hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

price
number >= 0

The price of the task (basket price for e-commerce)

driver
string

The identifier of the driver (urbantz user)

object (Requirements)

Required actions in the mobile application. It cannot be modified once the task is assigned to a round

object (TaskExecution)

Information collected by the driver during the execution of the task

Array of objects (TaskLog)

Log of the progress transition of the task

categories
Array of strings (Categories)

Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons.

object

Information about contactless delivery

object

If there are assets to picked up or to be left at the client

Array of objects

List of file attachments (pictures, delivery notes, etc...)

brandingTemplate
string (TaskInternalField)
Deprecated

This field is used for internal purposes only and should not be consumed. This field will be removed after January 1st, 2025.

timestamp
string <date-time>

The date when the webhook was sent to your server

Responses

Request samples

Content type
application/json
{
  • "createdBy": {
    },
  • "__v": 0,
  • "_id": "507f191e810c19729de860ea",
  • "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",
  • "items": [
    ],
  • "client": "507f191e810c19729de860ea",
  • "hub": "507f191e810c19729de860ea",
  • "hubName": "My Warehouse",
  • "associatedName": "Lumikko Oyj",
  • "associated": "5c3c63c23c32c30cb3cc1234c",
  • "dependency": "507f191e810c19729de860ea",
  • "hasDependency": "507f191e810c19729de860ea",
  • "round": "R01",
  • "archived": "string",
  • "actualTime": {
    },
  • "order": "string",
  • "paymentType": "CCOD",
  • "platform": "5c98f80a6b3dc61664c05cbf",
  • "platformName": "Cortedal SYS, Oy",
  • "endpoint": "5c3c645e3b37f30b3fc0240f",
  • "errorLocation": {
    },
  • "customerCalls": [
    ],
  • "issues": [
    ],
  • "notifications": [
    ],
  • "notificationSettings": {
    },
  • "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": "string",
  • "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",
  • "requires": {
    },
  • "execution": {
    },
  • "log": [
    ],
  • "categories": [
    ],
  • "contactless": {
    },
  • "assets": {
    },
  • "attachments": [
    ],
  • "brandingTemplate": "string",
  • "timestamp": "2019-04-01T08:31:05.121Z"
}

AnnouncementComplete

The AnnouncementComplete event is triggered whenever an announcement is completed, whether it succeeded or failed. This WebHook is available on the WebHooks tab of a Flow.

If the status is FAILED, the error object will be populated with a message and details of the error(s).

Request Body schema: application/json
timestamp
string <date-time>

The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp.

id
required
string

The internal ID of the announcement

status
required
string
Enum: "FAILED" "SUCCESS"

The announcement's status

start
required
string <date-time>

The timestamp of when the announcement was started

end
required
string <date-time>

The timestamp of when the announcement was completed

mode
required
string
Enum: "API" "FILE"

The way the announcement was provided

object (AnnouncementErrors)

The error information if the announcement's status is FAILED

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-13T12:34:56.012Z",
  • "id": "string",
  • "status": "FAILED",
  • "start": "2019-03-13T12:34:56.012Z",
  • "end": "2019-03-13T12:34:56.012Z",
  • "mode": "API",
  • "error": {
    }
}

AnnouncementCancelled

The AnnouncementCancelled event is triggered whenever someone deletes an announcement in the announcements tab of the web interface. This WebHook can be found in the WebHooks tab of a Flow.

When getting this WebHook, we send the bare minimum information about the tasks that were in the announcement, which means you'll get the internal identifier and the TaskId of each task affected by this announcement deletion. You can then use the Retrieve a specific task to get detailed information about the tasks.

Request Body schema: application/json
announcement
string (AnnouncementID)

The identifier of the announcement

Array of objects (TaskMinimalIdentifiers)
timestamp
string <date-time>

The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp.

Responses

Request samples

Content type
application/json
{
  • "announcement": "507f191e810c19729de860ea",
  • "tasks": [
    ],
  • "timestamp": "2019-03-13T12:34:56.012Z"
}

TicketCreated

The TicketCreated event is triggered whenever a ticket is created in your platform. This WebHook can be found in the WebHooks tab of the General platform settings.

If you want to obtain more information about the related task or round, you are invited to use our Retrieve a specific task and Retrieve a specific round endpoint.

Request Body schema: application/json
labels
Array of strings (TicketLabels)
status
string (TicketStatus)
Enum: "OPEN" "TREATED" "CLOSED"

The status of the ticket

when
string <date-time>

creation date of the ticket

Array of objects (TicketLog)

An array of log objects for that ticket

Array of objects (TicketComment)

a list of comments for the given ticket

_id
string (ID)
class
string
Enum: "task" "round"

The kind of ticket. A task ticket will have additional properties related to the task, and a round ticket will have additional properties related to the round.

object (TicketTask)

A task relation object. Provides the database ID as well as the TaskID. Only available if the class is 'task'.

round
string

The round database ID for this ticket

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

platform
string (ID)
associated
string (ID)
associatedName
string

The platform name to which the ticket is associated to. Used when tickets, rounds or tasks are going from a platform to another for example.

by
string (ID)
priority
number
Enum: 1 2 3

The priority of the ticket. 1 is for low, 2 for medium, 3 for high.

type
string

A string that defines the kind of ticket, as defined in the Ticket settings. Please note that only the types defined in the Ticket settings are allowed as a value.

title
string

Title of this ticket

object (TicketCategory)

Contains the information about the category the ticket has been set to. If no category is defined, it will be null.

object (UserRelation)
object (UserRelation)
description
string

The description of the ticket

userName
string

The full name of the creator of this ticket, as a string

assignedToName
string

The full name of the user assigned to this ticket, as a string

id
string (ID)
timestamp
string <date-time>

The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ],
  • "status": "OPEN",
  • "when": "2019-03-13T12:34:56.012Z",
  • "log": [
    ],
  • "comments": [
    ],
  • "_id": "507f191e810c19729de860ea",
  • "class": "task",
  • "task": {
    },
  • "round": "string",
  • "taskId": "my-task-id",
  • "platform": "507f191e810c19729de860ea",
  • "associated": "507f191e810c19729de860ea",
  • "associatedName": "Another delivery in the truck",
  • "by": "507f191e810c19729de860ea",
  • "priority": 1,
  • "type": "string",
  • "title": "string",
  • "category": {
    },
  • "assignedTo": {
    },
  • "user": {
    },
  • "description": "string",
  • "userName": "string",
  • "assignedToName": "string",
  • "id": "507f191e810c19729de860ea",
  • "timestamp": "2019-03-13T12:34:56.012Z"
}

TicketUpdated

The TicketUpdated event is triggered whenever a ticket is edited in your platform. This WebHook can be found in the WebHooks tab of the General platform settings.

The reason of the edit could be a manual change of some properties (change the priority, add a comment, ...) or an action taken on the ticket (Mark as treated, assign ticket to someone or self, ...).

If you want to obtain more information about the related task or round, you are invited to use our Retrieve a specific task and Retrieve a specific round endpoint.

Request Body schema: application/json
labels
Array of strings (TicketLabels)
status
string (TicketStatus)
Enum: "OPEN" "TREATED" "CLOSED"

The status of the ticket

when
string <date-time>

creation date of the ticket

Array of objects (TicketLog)

An array of log objects for that ticket

Array of objects (TicketComment)

a list of comments for the given ticket

_id
string (ID)
class
string
Enum: "task" "round"

The kind of ticket. A task ticket will have additional properties related to the task, and a round ticket will have additional properties related to the round.

object (TicketTask)

A task relation object. Provides the database ID as well as the TaskID. Only available if the class is 'task'.

round
string

The round database ID for this ticket

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

platform
string (ID)
associated
string (ID)
associatedName
string

The platform name to which the ticket is associated to. Used when tickets, rounds or tasks are going from a platform to another for example.

by
string (ID)
priority
number
Enum: 1 2 3

The priority of the ticket. 1 is for low, 2 for medium, 3 for high.

type
string

A string that defines the kind of ticket, as defined in the Ticket settings. Please note that only the types defined in the Ticket settings are allowed as a value.

title
string

Title of this ticket

object (TicketCategory)

Contains the information about the category the ticket has been set to. If no category is defined, it will be null.

object (UserRelation)
object (UserRelation)
description
string

The description of the ticket

userName
string

The full name of the creator of this ticket, as a string

assignedToName
string

The full name of the user assigned to this ticket, as a string

id
string (ID)
timestamp
string <date-time>

The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ],
  • "status": "OPEN",
  • "when": "2019-03-13T12:34:56.012Z",
  • "log": [
    ],
  • "comments": [
    ],
  • "_id": "507f191e810c19729de860ea",
  • "class": "task",
  • "task": {
    },
  • "round": "string",
  • "taskId": "my-task-id",
  • "platform": "507f191e810c19729de860ea",
  • "associated": "507f191e810c19729de860ea",
  • "associatedName": "Another delivery in the truck",
  • "by": "507f191e810c19729de860ea",
  • "priority": 1,
  • "type": "string",
  • "title": "string",
  • "category": {
    },
  • "assignedTo": {
    },
  • "user": {
    },
  • "description": "string",
  • "userName": "string",
  • "assignedToName": "string",
  • "id": "507f191e810c19729de860ea",
  • "timestamp": "2019-03-13T12:34:56.012Z"
}

TicketClosed

The TicketClosed event is triggered whenever a ticket is closed in your platform. This WebHook can be found in the WebHooks tab of the General platform settings.

A ticket that has been closed can no longer be modified.

If you want to obtain more information about the related task or round, you are invited to use our Retrieve a specific task and Retrieve a specific round endpoint.

Request Body schema: application/json
labels
Array of strings (TicketLabels)
status
string (TicketStatus)
Enum: "OPEN" "TREATED" "CLOSED"

The status of the ticket

when
string <date-time>

creation date of the ticket

Array of objects (TicketLog)

An array of log objects for that ticket

Array of objects (TicketComment)

a list of comments for the given ticket

_id
string (ID)
class
string
Enum: "task" "round"

The kind of ticket. A task ticket will have additional properties related to the task, and a round ticket will have additional properties related to the round.

object (TicketTask)

A task relation object. Provides the database ID as well as the TaskID. Only available if the class is 'task'.

round
string

The round database ID for this ticket

taskId
string (TaskId)

Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier.

platform
string (ID)
associated
string (ID)
associatedName
string

The platform name to which the ticket is associated to. Used when tickets, rounds or tasks are going from a platform to another for example.

by
string (ID)
priority
number
Enum: 1 2 3

The priority of the ticket. 1 is for low, 2 for medium, 3 for high.

type
string

A string that defines the kind of ticket, as defined in the Ticket settings. Please note that only the types defined in the Ticket settings are allowed as a value.

title
string

Title of this ticket

object (TicketCategory)

Contains the information about the category the ticket has been set to. If no category is defined, it will be null.

object (UserRelation)
object (UserRelation)
description
string

The description of the ticket

userName
string

The full name of the creator of this ticket, as a string

assignedToName
string

The full name of the user assigned to this ticket, as a string

id
string (ID)
timestamp
string <date-time>

The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ],
  • "status": "OPEN",
  • "when": "2019-03-13T12:34:56.012Z",
  • "log": [
    ],
  • "comments": [
    ],
  • "_id": "507f191e810c19729de860ea",
  • "class": "task",
  • "task": {
    },
  • "round": "string",
  • "taskId": "my-task-id",
  • "platform": "507f191e810c19729de860ea",
  • "associated": "507f191e810c19729de860ea",
  • "associatedName": "Another delivery in the truck",
  • "by": "507f191e810c19729de860ea",
  • "priority": 1,
  • "type": "string",
  • "title": "string",
  • "category": {
    },
  • "assignedTo": {
    },
  • "user": {
    },
  • "description": "string",
  • "userName": "string",
  • "assignedToName": "string",
  • "id": "507f191e810c19729de860ea",
  • "timestamp": "2019-03-13T12:34:56.012Z"
}

round.created

The round.created event is triggered whenever a new round has been created in your platform. This WebHook can be found under the WebHooks tab of the General platform settings.

If you wish to learn how to create a round, please visit the How to optimize/create rounds on our Help Center.

Request Body schema: application/json
timestamp
string <date-time>
type
string

The webhook event type which describes the new round status

eventType
string
Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed"

The webhook event type which describes the new round status

object (RoundWebhookBody)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "round.created",
  • "eventType": "round.created",
  • "round": {
    }
}

round.validated

The round.validated event is triggered whenever a round is validated. A round can be validated if and only if the current status of the round is CREATED. The WebHook can be found in the WebHooks tab of the General platform settings.

Once the round is validated, it is now possible to publish it, making it available for the drivers.

Request Body schema: application/json
timestamp
string <date-time>
type
string

The webhook event type which describes the new round status

eventType
string
Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed"

The webhook event type which describes the new round status

object (RoundWebhookBody)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "round.created",
  • "eventType": "round.created",
  • "round": {
    }
}

round.published

The round.published event is triggered whenever a round is published. A round can be published if and only if the current status of the round is VALIDATED. The WebHook can be found in the WebHooks tab of the General platform settings.

Once the round is published, drivers will be able to take it as a mission, and start preparing the round.

Request Body schema: application/json
timestamp
string <date-time>
type
string

The webhook event type which describes the new round status

eventType
string
Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed"

The webhook event type which describes the new round status

object (RoundWebhookBody)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "round.created",
  • "eventType": "round.created",
  • "round": {
    }
}

round.in_preparation

The round.in_preparation event is triggered whenever a round is being prepared by a driver or dispatcher. A round can be prepared if and only if the current status of the round is published. The WebHook can be found in the WebHooks tab of the General platform settings.

Once the round is prepared, it becomes possible to start delivering it. the status for a round being in the process of delivery is called ongoing.

Request Body schema: application/json
timestamp
string <date-time>
type
string

The webhook event type which describes the new round status

eventType
string
Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed"

The webhook event type which describes the new round status

object (RoundWebhookBody)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "round.created",
  • "eventType": "round.created",
  • "round": {
    }
}

round.ongoing

The round.ongoing event is triggered whenever a round is prepared by a driver or dispatcher, and the driver started driving to the first delivery point. The WebHook can be found in the WebHooks tab of the General platform settings.

Once the round is completed (all parcels have been either delivered, partially delivered or not delivered), the round will switch to the status completed.

Request Body schema: application/json
timestamp
string <date-time>
type
string

The webhook event type which describes the new round status

eventType
string
Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed"

The webhook event type which describes the new round status

object (RoundWebhookBody)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "round.created",
  • "eventType": "round.created",
  • "round": {
    }
}

round.completed

The round.completed event is triggered whenever a round is finished being delivered by a driver. The parcels could either be delivered, partially delivered, or not delivered. In any case, the round is marked as completed as there is no more address to reach to deliver or pickup one or more parcels. The WebHook can be found in the WebHooks tab of the General platform settings.

Request Body schema: application/json
timestamp
string <date-time>
type
string

The webhook event type which describes the new round status

eventType
string
Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed"

The webhook event type which describes the new round status

object (RoundWebhookBody)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "round.created",
  • "eventType": "round.created",
  • "round": {
    }
}

round.analytics (RDD)

The round.analytics event is triggered whenever a metric is available after a round is complete. The payload will change based on the type. This is a description of the payload when the type is for the Real Distance Driven metric

Request Body schema: application/json
timestamp
string <date-time>
type
string
Value: "REAL_DISTANCE_DRIVEN"

The type of analytics in the payload

eventType
string
Value: "round.analytics"

The webhook event type

object (RealDistanceDriven)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "REAL_DISTANCE_DRIVEN",
  • "eventType": "round.analytics",
  • "payload": {
    }
}

round.analytics (GHG)

The round.analytics event is triggered whenever a metric is available after a round is complete. The payload will change based on the type. This is a description of the payload when the type is for the Green House Gases metric

Request Body schema: application/json
timestamp
string <date-time>
type
string
Value: "GHG_EMISSION"

The type of analytics in the payload

eventType
string
Value: "round.analytics"

The webhook event type

object (RoundGhg)

Responses

Request samples

Content type
application/json
{
  • "timestamp": "2019-03-15T12:34:56.000Z",
  • "type": "GHG_EMISSION",
  • "eventType": "round.analytics",
  • "payload": {
    }
}

Zones

Zones are polygons representing delivery areas. The zones can be used in allocation rules, optimization problems, etc…

Retrieve zones

This endpoint fetches a paginated list of all the zones configured in your platform. It also allows to filter the list by specific criteria.

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

names
Array of strings <= 100 items

The zone names to search for. It's a case sensitive exact match search.

latitude
number [ -90 .. 90 ]
Example: latitude=50.824853

The latitude to search for

longitude
number [ -180 .. 180 ]
Example: longitude=4.365968

The longitude to search for

Responses

Response samples

Content type
application/json
[
  • {
    }
]