Urbantz API documentation (v2)

Download OpenAPI specification:

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 Schema: application/json
Array
_id
string (ID)
name
string

The name of the announcement

flux
string (ID)
endpoint
string (ID)
by
string (ID)
count
number

The number of imported tasks

updatedCount
number

The number of times the announcement was updated

platform
string

The internal identifier of the platform

mode
string
Enum: "FILE" "API" "UI"

The mode used to import the tasks

Array of objects (AnnouncementTargetFlux)
Array
_id
string (ID)
name
string

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

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

  • hub
  • shift
  • optimisation
  • date

An independent optimization problem occurs at a hub, on a particular date, during a specific shift in a defined flow (or flux).

date
string <date-time>
hub
string (ID)
status
string
Enum: "NON_OPTIMIZED" "IN_PROGRESS" "PARTIAL" "OPTIMIZED"

The optimization status of the target flux

logs
Array of objects

The logs of the optimization result

count
number

The number of imported tasks linked to the target flux

object (AnnouncementIssues)
geocoding
number

The number of geocoding errors

validation
number

The number of validation errors

jobs
Array of strings
published
boolean

if the flux is published

updated
string <date-time>

The date of the last update of that flux

validated
boolean

if the flux has been validated or not

object
rounds
Array of strings
tasks
Array of strings
status
string
Enum: "SUCCESS" "FAILED" "IN_PROGRESS"

The announcement's status

start
string <date-time>

The timestamp of when the announcement was received

end
string <date-time>

The timestamp of when the announcement was completed

isLocked
boolean

An announcement is locked when a round linked to it is started

object
details
Array of strings
object (AnnouncementIssues)
geocoding
number

The number of geocoding errors

validation
number

The number of validation errors

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 Schema: application/json
_id
string (ID)
name
string

The name of the announcement

flux
string (ID)
endpoint
string (ID)
by
string (ID)
count
number

The number of imported tasks

updatedCount
number

The number of times the announcement was updated

platform
string

The internal identifier of the platform

mode
string
Enum: "FILE" "API" "UI"

The mode used to import the tasks

Array of objects (AnnouncementTargetFlux)
Array
_id
string (ID)
name
string

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

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

  • hub
  • shift
  • optimisation
  • date

An independent optimization problem occurs at a hub, on a particular date, during a specific shift in a defined flow (or flux).

date
string <date-time>
hub
string (ID)
status
string
Enum: "NON_OPTIMIZED" "IN_PROGRESS" "PARTIAL" "OPTIMIZED"

The optimization status of the target flux

logs
Array of objects

The logs of the optimization result

count
number

The number of imported tasks linked to the target flux

object (AnnouncementIssues)
geocoding
number

The number of geocoding errors

validation
number

The number of validation errors

jobs
Array of strings
published
boolean

if the flux is published

updated
string <date-time>

The date of the last update of that flux

validated
boolean

if the flux has been validated or not

object
rounds
Array of strings
tasks
Array of strings
status
string
Enum: "SUCCESS" "FAILED" "IN_PROGRESS"

The announcement's status

start
string <date-time>

The timestamp of when the announcement was received

end
string <date-time>

The timestamp of when the announcement was completed

isLocked
boolean

An announcement is locked when a round linked to it is started

object
details
Array of strings
object (AnnouncementIssues)
geocoding
number

The number of geocoding errors

validation
number

The number of validation errors

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

Response Headers
Location
string

The URI to download the attachment

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

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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.

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
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

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)

Responses

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object (CarrierTaskStatusSignature)

The signature of the customer collected by the driver

name
string

Name of the person who signed.

image
string <url>

URL of the picture taken as a proof of the successful task.

comment
string (CarrierTaskStatusComment)

Comment of the client when the delivery/pickup is successful.

picture
string <url> (CarrierTaskStatusPicture)

URL of the picture taken as a proof of the successful task.

object

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object (CarrierTaskStatusReason)

The reason why the task could not be delivered/picked up.

message
string

Reason why the task failed. It can be a failure reason code as configured in Administration > Platform > General > Failure Reasons, or a free text that will be parsed as a custom reason.

picture
string <url>

Url of the picture taken as a proof of the failed task.

object

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object (CarrierTaskStatusSignature)

The signature of the customer collected by the driver

name
string

Name of the person who signed.

image
string <url>

URL of the picture taken as a proof of the successful task.

comment
string (CarrierTaskStatusComment)

Comment of the client when the delivery/pickup is successful.

picture
string <url> (CarrierTaskStatusPicture)

URL of the picture taken as a proof of the successful task.

object

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object (CarrierTaskStatusReason)

The reason why the task could not be delivered/picked up.

message
string

Reason why the task failed. It can be a failure reason code as configured in Administration > Platform > General > Failure Reasons, or a free text that will be parsed as a custom reason.

picture
string <url>

Url of the picture taken as a proof of the failed task.

object (CarrierTaskStatusPosition)

Position of the driver at the moment of the task completion

latitude
number

Latitude

longitude
number

Longitude

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

property name*
additional property
object

Responses

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)

Responses

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

Responses

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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.

total
boolean (CarrierTaskStatusTotal)

Specify if the totality of items should change to this status. Only used if the update type is 'total'.

items
Array of strings (CarrierTaskStatusItems)
object (CarrierTaskStatusSignature)

The signature of the customer collected by the driver

name
string

Name of the person who signed.

image
string <url>

URL of the picture taken as a proof of the successful task.

comment
string (CarrierTaskStatusComment)

Comment of the client when the delivery/pickup is successful.

picture
string <url> (CarrierTaskStatusPicture)

URL of the picture taken as a proof of the successful task.

Responses

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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.

start
string <date-time>

The start of the time window. The value provided must be an ISO 8601 date time string

stop
string <date-time>

The end of the time window. The value provided must be an ISO 8601 date time string

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

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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.

longitude
required
number [ -180 .. 180 ]
latitude
required
number [ -90 .. 90 ]
accuracy
number
altitude
number
required
Array of objects [ 1 .. 200 ] items

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

Array ([ 1 .. 200 ] items)
extTrackId
required
string <= 255 characters

The external task identifier to use for mapping data between the external carrier and Urbantz.

eta
string <date-time> <= 27 characters

Estimated time of arrival at the recipient location.

tasksBefore
integer [ 0 .. 199 ]

The number of tasks left to be completed before the task.

Responses

Response Schema: application/json
Array
internalId
string

The task internal identifier.

taskId
string

The taskId to identify a specific task.

extTrackId
string

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

success
boolean

Indicates if the update for the particular task was successful.

object

Populated if the update was unsuccessful.

code
number
message
string

The reason of failure, if any

Response Schema: application/json
code
number
message
string

The reason of failure

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 Schema: application/json
Array
id
string

The identifier of the hub

externalId
string

The external identifier of the hub

name
string

The name of the hub

object (HubAddress)
street
string
number
string
city
string
zip
string
country
string

An ISO_3166-1_alpha-2 country code (2 letters).

object

The coordinates of the hub

latitude
number [ -90 .. 90 ]
longitude
number [ -180 .. 180 ]
owner
string

The snake-case identifier of the platform that owns the hub

Response Schema: application/json
error
string
Enum: "Please verify the content of your request." "Invalid announcement. The announcement (body) should be an array with at least one task.\""

Description of the error

Response Schema: application/json
error
string

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 Schema: application/json
Array
id
string (ID)
event
string
Enum: "driver-approaching" "task-ongoing" "task-eta-approaching" "task-next-in-line" "task-optimized" "task-completed-success" "task-completed-failed" "task-ready-to-collect" "task-unplanned" "task-missing" "task-scheduled" "task-replanned" "task-time-window-approaching" "task-unplanned-reminder"

Name of the event

object (contact-2)
name
string <= 255 characters

Recipient name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

language
string <= 255 characters

Contact language 2 letter ISO code

channel
string
Enum: "SMS" "EMAIL"

The channel used to send the notification

content
string

Message (text) sent to the recipient. In case of an email, it corresponds to the body

status
string
Enum: "Pending" "Sent" "Delivered" "Failed" "Rejected" "Unknown"

Status of the notification

object (notification-error)
code
integer

The error code of the action

message
string

The reason of the failure.

when
string <date-time>

The ISO 8601 date of when the transition of status occurred.

Response Schema: application/json
error
string
Enum: "Please verify the content of your request." "Invalid announcement. The announcement (body) should be an array with at least one task.\""

Description of the error

Response Schema: application/json
error
string

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
  • optimisation
  • 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 Schema: application/json
Array
_id
string (ID)
object

A list of dates and times giving the actual real time the driver did the actions for this round.

hasPrepared
string <date-time>
Default: null

The moment when the driver (or dispatcher) prepared the round. null if we do not have information.

hasStarted
string <date-time>
Default: null

The moment when the driver started the round. null if we do not have information.

hasFinished
string <date-time>
Default: null

The moment when the driver finished the round. null if we do not have information.

preparationTime
integer
Default: null

The time the driver or dispatcher took to prepare the round.

hasLasted
integer
Default: null

The time the driver took to execute the round.

name
string

The name of the round

status
string (RoundStatus)
Enum: "CREATED" "VALIDATED" "PUBLISHED" "ONGOING" "ASSIGNED" "IN_PREPARATION" "COMPLETED" "READY" "ARRIVED" "IN_DELIVERY"
activity
string (Activity)
Enum: "classic" "express" "scheduler"

The activity type for the entity.

shift
string (Shift)

A reference of a shift defined at the platform level.

targetFlux
string (TargetFlux)

A target flux represents an independent problem for the optimizer. A target flux reference is typically a combination of hub-date-shift.

platform
string (ID)
object
exampleKey
string
labelsAndSkills
Array of strings
date
string <date-time>

The date the round should be executed

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.

property name*
additional property
number >= 0
object
_id
string (ID)
externalId
string

external identifier

startTime
string <date-time>

The time the round should start

endTime
string <date-time>

The time the round is expected to be finished

validated
boolean

If the round is validated or not.

totalViolationTime
integer

The total violation time at all orders and breaks on the round.

totalWaitTime
integer

The total wait time at all orders, hubs, and breaks on the round.

totalDistance
number

The total distance in meters for the round

totalTravelTime
integer

The total travel time for the round in milliseconds.

totalBreakServiceTime
integer

The total service time spent at all breaks on the round in minutes.

totalOrderServiceTime
integer

The total service time spent at all orders on the round in minutes.

totalTime
integer

The total duration of the round

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

totalCost
number

The total operating cost of the route, which is the sum of the following attribute values: FixedCost, RegularTimeCost, OvertimeCost, DistanceCost.

orderCount
integer

The number of orders (stops) assigned to this round.

updated
string <date-time>

Last update (modification) time

reloads
Array of strings
flux
string

The identifier of the optimization used to create the round

id
string

The internal identifier of this round. If _id exists as a property, their values should be shared.

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.

orderDone
integer

The number of orders that are done (delivered or not). To compare with orderCount, the total of orders in this round.

Array of objects
Array
name
string

The name of the sender

reference
string

The reference of this sender

count
integer

The number of tasks from this sender on this round

_id
string

The internal identifier for this sender in Urbantz

picture
string

The picture of the round overview (Google Maps). Might not be provided.

object (UserSummaryId)

The user object. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

Array of objects (Stop)
Array
stopType
integer
Enum: 0 1 2

The type of stop. 0 = order, 1 = hub, 2 = break

type
string
Enum: "hub" "pickup" "delivery" "break"

The order type for the stop

stopSequence
integer

similar to the sequence number, except it takes into account reloadings if any, and hub start-stop. A one sequence delivery will have actually 3 sequences (hub - delivery - hub). sequence will be given on the delivery only, and will be 1, but its stopSequence will be 2, as hub is stopSequence 1.

travelDistance
number

The distance to be traveled in kilometers from the previous stop.

arriveTime
string <date-time>

The time of the expected arrival of the user at the stop.

departTime
string <date-time>

The time of the expected departure of the user from the stop.

parcel
string (ID)
sequence
integer

The sequence of the stop in the round.

taskId
string

external identifier

taskReference
string (TaskReference) <= 256 characters

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

violationTime
integer
waitTime
integer
serviceTime
integer
travelTime
integer
coordinates
Array of numbers
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

closureDate
string <date-time> (ClosureDate)

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

object
time
number

how long the round is delayed in milliseconds

when
string <date-time>

the last update date

object (RoundVehicle)
name
string
id
string

The internal identifier of the vehicle. If _id exists, their value should be shared.

_id
string (ID)

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 Schema: application/json
_id
string (ID)
object

A list of dates and times giving the actual real time the driver did the actions for this round.

hasPrepared
string <date-time>
Default: null

The moment when the driver (or dispatcher) prepared the round. null if we do not have information.

hasStarted
string <date-time>
Default: null

The moment when the driver started the round. null if we do not have information.

hasFinished
string <date-time>
Default: null

The moment when the driver finished the round. null if we do not have information.

preparationTime
integer
Default: null

The time the driver or dispatcher took to prepare the round.

hasLasted
integer
Default: null

The time the driver took to execute the round.

name
string

The name of the round

status
string (RoundStatus)
Enum: "CREATED" "VALIDATED" "PUBLISHED" "ONGOING" "ASSIGNED" "IN_PREPARATION" "COMPLETED" "READY" "ARRIVED" "IN_DELIVERY"
activity
string (Activity)
Enum: "classic" "express" "scheduler"

The activity type for the entity.

shift
string (Shift)

A reference of a shift defined at the platform level.

targetFlux
string (TargetFlux)

A target flux represents an independent problem for the optimizer. A target flux reference is typically a combination of hub-date-shift.

platform
string (ID)
object
exampleKey
string
labelsAndSkills
Array of strings
date
string <date-time>

The date the round should be executed

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.

property name*
additional property
number >= 0
object
_id
string (ID)
externalId
string

external identifier

startTime
string <date-time>

The time the round should start

endTime
string <date-time>

The time the round is expected to be finished

validated
boolean

If the round is validated or not.

totalViolationTime
integer

The total violation time at all orders and breaks on the round.

totalWaitTime
integer

The total wait time at all orders, hubs, and breaks on the round.

totalDistance
number

The total distance in meters for the round

totalTravelTime
integer

The total travel time for the round in milliseconds.

totalBreakServiceTime
integer

The total service time spent at all breaks on the round in minutes.

totalOrderServiceTime
integer

The total service time spent at all orders on the round in minutes.

totalTime
integer

The total duration of the round

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

totalCost
number

The total operating cost of the route, which is the sum of the following attribute values: FixedCost, RegularTimeCost, OvertimeCost, DistanceCost.

orderCount
integer

The number of orders (stops) assigned to this round.

updated
string <date-time>

Last update (modification) time

reloads
Array of strings
flux
string

The identifier of the optimization used to create the round

id
string

The internal identifier of this round. If _id exists as a property, their values should be shared.

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.

orderDone
integer

The number of orders that are done (delivered or not). To compare with orderCount, the total of orders in this round.

Array of objects
Array
name
string

The name of the sender

reference
string

The reference of this sender

count
integer

The number of tasks from this sender on this round

_id
string

The internal identifier for this sender in Urbantz

picture
string

The picture of the round overview (Google Maps). Might not be provided.

object (UserSummaryId)

The user object. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

Array of objects (Stop)
Array
stopType
integer
Enum: 0 1 2

The type of stop. 0 = order, 1 = hub, 2 = break

type
string
Enum: "hub" "pickup" "delivery" "break"

The order type for the stop

stopSequence
integer

similar to the sequence number, except it takes into account reloadings if any, and hub start-stop. A one sequence delivery will have actually 3 sequences (hub - delivery - hub). sequence will be given on the delivery only, and will be 1, but its stopSequence will be 2, as hub is stopSequence 1.

travelDistance
number

The distance to be traveled in kilometers from the previous stop.

arriveTime
string <date-time>

The time of the expected arrival of the user at the stop.

departTime
string <date-time>

The time of the expected departure of the user from the stop.

parcel
string (ID)
sequence
integer

The sequence of the stop in the round.

taskId
string

external identifier

taskReference
string (TaskReference) <= 256 characters

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

violationTime
integer
waitTime
integer
serviceTime
integer
travelTime
integer
coordinates
Array of numbers
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

closureDate
string <date-time> (ClosureDate)

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

object
time
number

how long the round is delayed in milliseconds

when
string <date-time>

the last update date

object (RoundVehicle)
name
string
id
string

The internal identifier of the vehicle. If _id exists, their value should be shared.

_id
string (ID)

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.

Array
type
string
Enum: "hub" "custom" "pickup" "delivery" "break"

The type for the stop.

If the round starts/ends at the hub, the value for the stop must be hub and you must provide the hub property for the round.

If the round starts/ends at the driver's place, the value for the stop must be driver and you must provide the driver property.

If the round starts/ends at an order location, you must use the appropriated order type delivery or pickup.

You cannot start nor end a round with a break.

id
string

The internal id to identify a specific task.

This value is optional if taskId is provided. It cannot be mixed with taskId in the same round.

example: 5ffeb8445389a819937a095e

taskId
string

The taskId to identify a specific task.

This value is optional if id is provided. It cannot be mixed with id in the same round.

example: your-own-identifier

arriveTime
string <date-time>

The expected time arrival (ETA) of the driver at the stop.

The provided value should be an ISO 8601 date time string.

This value can be omitted for all stops or provided for all stops. It is not possible to set the property for only some of the stops.

If arriveTime is provided, as well as startTime and endTime for the overall round, the arriveTime value of the first stop must match the startTime of the round and the arriveTime value of the last stop must match the endTime of the round.

The tasks must be announced for the date specified in arriveTime in order to be retrieved. When omitted, the task must be announced for the same date as the round date. As a result, this value is mandatory if you plan to create a round on multiple days.

example: 2021-02-14T13:37:00.000Z

location
Array of numbers

It represents the latitude and longitude.

This value is only required for stops of type break and for custom starting/ending address.

example: [48.8583701, 2.2922926]

duration
number

Time spent for a break in minutes.

This value is only required for a break.

example: 10

Responses

Response Schema: application/json
Array
round
string

The targeted round name.

errors
number

The number of errors that prevent to create the round.

Array of objects

The detailed errors that prevent to create the round.

Array
code
string

An internal error code describing the error.

message
string

The generic description of the error.

details
Array of strings

The detailed description of the error.

orders
Array of strings

The id of the tasks added in the round.

message
string

The generic message acknowledging the success or failure of the round creation.

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 Schema: application/json
realDistanceInMeter
number
confidenceLevel
string
Enum: "HIGH" "LOW" "N/A"
when
string <date-time>

The timestamp of when the real distance calculation completed

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 Schema: application/json
totalCo2Emission
number

Emission in grams

totalDistanceInMeter
number
distanceType
string
Enum: "REAL" "PLANNED"
vehicleType
string
energyType
string
when
string <date-time>

The timestamp of when the calculation completed

roundStartDate
string <date-time>
roundEndDate
string <date-time>
Array of objects
Array
id
string
weightInKg
number
defaultWeightUsed
boolean
co2Emission
number

Emission in grams

accuracy
string

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": [
    ]
}

Remove a task from a round

This endpoint allows the removal of a task from a round. It only accepts one simultaneous request per round. This means that if two tasks in the same round need to be removed, the requests must be made sequentially. However, this rule does not apply if the tasks belong to different rounds. To remove a task from its round:

  • The task must be assigned to a round.
  • The task’s progress must not be COMPLETED, READY_TO_COLLECT, or MISSING.
  • The round status must not be COMPLETED.
Authorizations:
PlatformKeyBasicAuth
path Parameters
id
required
string (ID)
Example: 507f191e810c19729de860ea

The round identifier

task
required
string (ID)
Example: 507f191e810c19729de860ea

The internal identifier of the task

Responses

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

Search by the start of the time window. It must be provided in the format YYYY-MM-DD. If the unplanned parameter is set to 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 Schema: application/json
Array
_id
string (InternalTaskID)

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

zone
string <= 255 characters
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.

type
required
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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

client
string (ClientID)

The sender identifier

hub
string (HubID)

The hub identifier

hubName
string

The hub name

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.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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

updated
string <date-time>

when the task was updated for the last time

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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

associatedName
string

The name of the associated platform

associated
string

The unique identifier of the associated platform

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

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

date
string <date-time>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (Requirements)

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

object (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

object (TaskAlert)
when
string <date-time>
solved
string <date-time>
data
object
service
string

In specific cases, can be used as an alternative to flux, but such use could have a performance cost.

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (TaskReturnedProductsArray)

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

Array
_id
string (ID)
barcode
string
description
string
name
required
string
productId
required
string
type
string
unitPrice
number >= 0
quantity
required
integer >= 1

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 (AnnouncedItem)
Array
type
string
name
string <= 255 characters
description
string
barcode
string
barcodeEncoding
string
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"
reference
string
quantity
integer >= 1
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.

property name*
additional property
number >= 0
labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

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

property name*
additional property
object
group
string <= 128 characters
hasBeenPaid
boolean

Indicates if the task has been paid by the recipient

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

required
object (AnnouncedAddress)
building
string
number
string
street
required
string
city
string
zip
string
country
string

An ISO_3166-1_alpha-2 country code (2 letters).

longitude
number
latitude
number
addressLines
Array of strings
Array of objects (AnnounceTaskProductsArray)

A list of products that the delivery will include

Array
productId
string
name
string
description
string
type
string
barcode
required
string

The barcode of the product is mandatory

quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
object (Requirements)

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

object (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

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

property name*
additional property
object
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

activated
boolean

Is it a click and collect task

point
string

The externalId or internalId of the collection point

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

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

Response Schema: application/json
announcement
string
received
number
time
string <date-time>
Response Schema: application/json
error
string
Enum: "Please verify the content of your request." "Invalid announcement. The announcement (body) should be an array with at least one task.\""

Description of the error

Response Schema: application/json
error
string

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 Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

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 (TaskPaymentType)
Enum: "CCOD" "COD" "(null value)"

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

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
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

property name*
additional property
object
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.

property name*
additional property
number >= 0
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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

required
object
geometry
required
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
required
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

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)
Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

object (Requirements)

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

object (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

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

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

object (Collect)

The click and collect information

activated
boolean

Is it a click and collect task

point
string

The externalId or internalId of the collection point

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

Array of objects (TaskReturnedProductsArray)

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

Array
_id
string (ID)
barcode
string
description
string
name
required
string
productId
required
string
type
string
unitPrice
number >= 0
quantity
required
integer >= 1
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)

For internal use only. Please do not use.

recalculateServiceTime
boolean
Default: false

Recalculates service time based on preconfigured service time rules.

Responses

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

Request samples

Content type
application/json
{
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "paymentType": "CCOD",
  • "skills": [
    ],
  • "products": [
    ],
  • "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": {
    },
  • "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 (TaskPaymentType)
Enum: "CCOD" "COD" "(null value)"

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

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
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

property name*
additional property
object
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.

property name*
additional property
number >= 0
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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

required
object
geometry
required
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
required
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

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)
Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

object (Requirements)

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

object (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

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

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

object (Collect)

The click and collect information

activated
boolean

Is it a click and collect task

point
string

The externalId or internalId of the collection point

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

Array of objects (TaskReturnedProductsArray)

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

Array
_id
string (ID)
barcode
string
description
string
name
required
string
productId
required
string
type
string
unitPrice
number >= 0
quantity
required
integer >= 1
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)

For internal use only. Please do not use.

recalculateServiceTime
boolean
Default: false

Recalculates service time based on preconfigured service time rules.

Responses

Response Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

Request samples

Content type
application/json
{
  • "taskId": "my-task-id",
  • "taskReference": "task-ref-001-d",
  • "paymentType": "CCOD",
  • "skills": [
    ],
  • "products": [
    ],
  • "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": {
    },
  • "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 Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

country
string <= 255 characters

Country

geocodeScore
integer [ 0 .. 100 ]

For internal purposes only. The confidence of the geocoder

addressLines
Array of strings <= 4 items [ items <= 255 characters ]

Unformatted address information. To use only when it is not possible to identify the previous fields in the source data.

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 (RequirementsPickup)

Pickup actions

object (RequirementsPickupDispatcher)

Actions when the package arrives to the hub.

scan
boolean
Default: false

The dispatcher has to scan the package when it arrives to the hub.

object (RequirementsPickupDriver)

Actions during the pick up

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

scan
boolean
Default: false

Scan the barcode is mandatory

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of pick up is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsPickupFailure)

Actions when the pick up fails

photo
boolean
Default: false

A picture as a proof of the failed pick up

object (RequirementsDelivery)

Delivery actions

object (RequirementsDeliveryDispatcher)

Actions during the delivery

scan
boolean
Default: false

Scanning the barcode before the driver preparation is mandatory.

object (RequirementsDeliveryDriver)

Actions during the preparation and the delivery.

contactless
boolean
Default: false

The recipient must provide a PIN code to accept the pickup/delivery.

prepCheckList
boolean
Default: false

The preparation of the items by a check list is mandatory.

prepScan
boolean
Default: false

The preparation of the items by scanning the barcode is mandatory.

signature
boolean
Default: false

The signature of the customer is mandatory

signatureAndComment
boolean
Default: false

The signature and comment of the customer is mandatory

signatureAndItemConcerns
boolean
Default: false

The signature of the customer is mandatory and the customer can state concerns about the condition of delivered items

scan
boolean
Default: false

Scan the barcode at the delivery moment is mandatoryRN0XILZ0!

comment
boolean
Default: false

The customer comment is mandatory

photo
boolean
Default: false

A picture as a proof of delivery is mandatory

object (RequirementsPickupStop)

Actions when the driver arrives at the stop

onSite
boolean
Default: false

The driver must indicate his arrival

object (RequirementsDeliveryFailure)

Actions when the delivery fails

photo
boolean
Default: false

A picture as a proof of the failed delivery

object (RequirementsOther)
object (RequirementsOtherDriver)

Other actions required

timer
boolean
Default: false

Start and stop a timer to measure the service time

object (TaskExecution)

Information collected by the driver during the execution of the task

successComment
string

Comment of the client when the delivery is successful.

successPicture
string

URL of the picture taken as a proof of the successful task.

object (TaskExecutionFailedReason)
reasonId
string (ID)
reason
string

Reason why the task failed.

custom
string

Custom reason why the task failed.

picture
string

URL of the picture taken as a proof of the failed task.

object

Time the driver spent on a task

Array of objects
Array
type
string

The type of timer

time
string <date-time>
object (TaskExecutionSignature)
data
string

URL of the picture taken as a proof of the successful task.

name
string

Name of the person who signed.

object (Position)

Position of the driver at the moment of the task completion

accuracy
integer

Accuracy of the position in percentage

altitude
integer

Altitude

heading
integer

heading

latitude
number
longitude
number
speed
integer
timestamp
integer
object

Information about the contactless delivery

forced
boolean

Indicate if the pincode was skipped

reason
string

the reason for skipping the pincode

Array of objects (TaskLog)

Log of the progress transition of the task

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
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

by
string

The user or system responsible for the status transition.

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

pin
string

The PIN code used for contactless delivery

object

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

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects (DeliveryAssets)
Array
assetId
string

identifier field, could be anything

name
string

name of the asset, example, "bottles"

price
number

the amount charged for the assets

amount
number

amount of assets being delivered/picked up

Array of objects

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

Array
_id
string

The unique identifier of attachment

name
string

The name of the printing template used

url
string

The relative URI path to the attachment (see Attachments)

brandingTemplate
string (TaskInternalField)

For internal use only. Please do not use.

Response Schema: application/json
code
integer

The error code of the action

message
string

The reason of the failure.

tasks
Array of strings (ID)

an array of task database IDs. Displayed only if there is a conflict with the taskID, such as duplicates.

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 Schema: application/json
object (UserSummaryExternal)

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

firstName
string
lastName
string
_id
string (ID)
id
string (ID)
externalId
string

The external identifier of a user. Can be undefined if account is old. Unique accross the same platform.

__v
number

For internal use only. Please do not use.

_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.

Array
_id
string (ItemID)

The identifier of the item

type
string <= 255 characters

Item type defined in the platform configuration

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

name
string <= 255 characters

Item name

description
string <= 255 characters

Item description

barcode
string <= 128 characters

Item barcode

barcodeEncoding
string <= 20 characters
Default: "CODE128"
Enum: "CODE128" "EAN13" "CODE39" "MSI"

Item barcode encoding

reference
string <= 256 characters

Item external reference

quantity
integer

Quantity of units of his item. The dimensions of the item will be multiplied by the number specified in this field.

processedQuantity
integer

Quantity of processed units of this item. If not specified then is considered that is not changed (the initial value is the item quantity).

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.

property name*
additional property
number >= 0
object (Damaged)

Indicates if the item is damaged

confirmed
boolean
Default: false

True if the item is damaged

pictures
Array of strings

List of pictures taken of the item

labels
Array of strings (ItemLabels)

Labels the vehicle must have to execute the item. Only labels which have been defined on the platform can be used.

skills
Array of strings (ItemSkills)

Skills the driver must have to execute the item. Only skills which have been defined on the platform can be used.

Array of objects (ItemLog)

Log of the status transition of the item

Array
_id
string (ID)
when
string <date-time>

The timestamp of when the transition of status occurred.

to
string (ItemStatus)
Enum: "PENDING" "RECEIVED" "ARRIVED" "PREPARED" "DEPARTED" "NOT_DELIVERED" "DELIVERED" "RETURNED" "MISSING" "PICKED_UP" "NOT_PICKED_UP" "TRANSFERED" "OPEN" "STARTED" "HOLD" "CLOSED"
by
string

The user or system responsible for the status transition.

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

property name*
additional property
object
group
string <= 128 characters

Barcode of the group in which the item is placed

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)

For internal use only. Please do not use.

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

object
when
string <date-time>

when the driver arrived at the delivery location (in ISO 8601 format)

object

location indicated by the driver

type
string
Default: "Point"
geometry
Array of numbers
forced
boolean
Default: false

indicates if the driver was not at the delivery location and forced the delivery

isCorrectAddress
boolean

indicates if the driver was in a different location but it was correct

order
string (TaskInternalField)

For internal use only. Please do not use.

paymentType
string (TaskPaymentType)
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
addressLines
Array of strings
geocodeScore
number
object
type
string
geometry
Array of numbers
Array of objects

The list of calls recorded by the driver

Array
when
string <date-time>

When the call was recorded (in ISO 8601 format)

by
string

The user identifier of this call

Array of objects

Issues occurred during the announcement of the task

Array
type
string
Enum: "GEOCODING" "VALIDATION"
code
number
line
number
error
string
Array of objects

List of manual SMS notifications sent to the recipient

Array
notificationId
string
sentDate
string <date-time>

When the notification was sent (in ISO 8601 format)

object (TaskDriver)

The driver of the task. It is an Urbantz user. Can be null.

firstName
string
lastName
string
email
string

Email of the user. May be provided or not depending on the context.

phoneNumber
string

Phone number of the user. May be provided or not depending on the context.

picture
string

Picture relative link of the user. May be provided or not depending on the context.

object
name
string

The type of reference

value
string

The value of the reference

_id
string (ID)
externalId
string

The external identifier of the user. Can be undefined if account is old. Unique accross the same platform.

object (TaskNotificationSettings)

Notification settings for this task

sms
boolean

Should the task trigger sms notifications

email
boolean

Should the task trigger email notifications

replanned
boolean
sourceHash
string (TaskInternalField)

For internal use only. Please do not use.

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

Array
productId
string
name
string
description
string
type
string
barcode
string
quantity
integer >= 1
unitPrice
number >= 0
isSubstitution
boolean
quantityRejected
integer >= 0
object

The rejected reason associated with this product

_id
string (ID)
name
string
hasRejectedProducts
boolean
Default: false

If the task has one or more rejected products

activity
string (TaskInternalField)

For internal use only. Please do not use.

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.

serviceTime
number

It is the duration in seconds urbantz calculated

tasksDeliveredInSameStop
number

Specifies the number of tasks that were completed during this time without moving the vehicle

confidence
string
Enum: "HIGH" "LOW"

It represents the level of confidence on the calculated service time

version
number

It is the version of the algorithm

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>

USE TIME WINDOW ONLY WITH ISO DATES INSTEAD.

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

property name*
additional property
object
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.

property name*
additional property
number >= 0
object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object

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

start
string <date-time>

The start of the time window. The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

stop
string <date-time>

The end of the time window.The value provided should either be an ISO 8601 date time string or a string in the HH:mm format.

object (Contact)

Information of the recipient of the task

account
string <= 255 characters

Contact account number

name
string <= 255 characters

Contact company name

person
string <= 255 characters

Contact first and last name

phone
string <= 255 characters

Contact phone number

email
string <= 255 characters

Contact email address

extraPhones
Array of strings[ items <= 255 characters ]

List of phone numbers to send SMS notifications

extraEmails
Array of strings[ items <= 255 characters ]

List of emails to send email notifications

language
string <= 255 characters

Contact language 2 letter ISO code

object (BuildingInfo)
floor
number [ -200 .. 200 ]

Floor number

hasElevator
boolean

Indicates if the building has elevator

digicode1
string <= 255 characters

Digicode

digicode2
string <= 255 characters

Second digicode

hasInterphone
boolean

Indicates if the building has interphone

interphoneCode
string <= 255 characters

Interphone code

object (Address)

Geocoded address of the task

building
string <= 255 characters

Extra information about the building.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

city
string <= 255 characters

City

zip
string <= 255 characters

Postal code

origin
string

The origin of this address

country
string <= 255 characters

Country

object (Location)
geometry
Array of numbers (Geometry) [ items = 2 items ]
type
string
Default: "Point"

The type of location. Usually "Point"

address
string

The full address of the address

addressLines
Array of strings
geocodeScore
number [ 0 .. 100 ]

internal use only. The accuracy of the localisation

countryCode
string = 3 characters

The ISO 3166-1 alpha-3 code of the country

object (SourceAddress)

Address provided at announcement

building
string <= 255 characters

Extra information about the building. This data will be copied to the parsed address but it won't be taken into account during the geocoding process.

number
string <= 255 characters

Street number

street
required
string <= 255 characters

Street name

object (Location)