Urbantz API documentation (v2)
Download OpenAPI specification:
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.
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:
account_snakethe snake-case identifier used in the URL of your platform or sender portal.account_typethe 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_tokenis the Bearer token that will be passed to the Urbantz APIexpires_inindicates 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}';
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 is0.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.
Navigating Through Pages
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.
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.
Feel free to contact our Support Team if any question remains after reading this documentation our looking up in our Help center.
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:
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
| _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
| |||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
object (AnnouncementIssues) | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
[- {
- "_id": "507f191e810c19729de860ea",
- "name": "string",
- "flux": "507f191e810c19729de860ea",
- "endpoint": "507f191e810c19729de860ea",
- "by": "507f191e810c19729de860ea",
- "count": 0,
- "updatedCount": 0,
- "platform": "4D3F12345AAAF30B2DD1CCFB",
- "mode": "FILE",
- "targetFluxes": [
- {
- "_id": "507f191e810c19729de860ea",
- "name": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
- "date": "2019-03-13T12:34:56.012Z",
- "hub": "507f191e810c19729de860ea",
- "status": "NON_OPTIMIZED",
- "logs": [
- { }
], - "count": 0,
- "issues": {
- "geocoding": 0,
- "validation": 0
}, - "jobs": [
- "string"
], - "published": true,
- "updated": "2019-03-13T12:34:56.012Z",
- "validated": true,
- "updateWarnings": {
- "rounds": [
- "string"
], - "tasks": [
- "string"
]
}
}
], - "status": "SUCCESS",
- "start": "2019-03-13T12:34:56.012Z",
- "end": "2019-03-13T12:34:56.012Z",
- "isLocked": true,
- "error": {
- "details": [
- "bad geocoding"
]
}, - "issues": {
- "geocoding": 0,
- "validation": 0
}
}
]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:
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
| |||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
object (AnnouncementIssues) | |||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
{- "_id": "507f191e810c19729de860ea",
- "name": "string",
- "flux": "507f191e810c19729de860ea",
- "endpoint": "507f191e810c19729de860ea",
- "by": "507f191e810c19729de860ea",
- "count": 0,
- "updatedCount": 0,
- "platform": "4D3F12345AAAF30B2DD1CCFB",
- "mode": "FILE",
- "targetFluxes": [
- {
- "_id": "507f191e810c19729de860ea",
- "name": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
- "date": "2019-03-13T12:34:56.012Z",
- "hub": "507f191e810c19729de860ea",
- "status": "NON_OPTIMIZED",
- "logs": [
- { }
], - "count": 0,
- "issues": {
- "geocoding": 0,
- "validation": 0
}, - "jobs": [
- "string"
], - "published": true,
- "updated": "2019-03-13T12:34:56.012Z",
- "validated": true,
- "updateWarnings": {
- "rounds": [
- "string"
], - "tasks": [
- "string"
]
}
}
], - "status": "SUCCESS",
- "start": "2019-03-13T12:34:56.012Z",
- "end": "2019-03-13T12:34:56.012Z",
- "isLocked": true,
- "error": {
- "details": [
- "bad geocoding"
]
}, - "issues": {
- "geocoding": 0,
- "validation": 0
}
}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:
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
| Location | string The URI to download the attachment |
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:
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "extTrackId": "ext-12345"
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "extTrackId": "ext-12345"
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
path Parameters
| extTrackId required | string (ExtTrackId) Example: ext-12345 The extTrackId of the task |
Request Body schema: application/json
| updatedTime | string <date-time> (CarrierTaskStatusUpdatedTime) The date-time of the operation in ISO date format | ||||
| updateType | string (CarrierTaskStatusUpdateType) Enum: "id" "barcode" "total" Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all. | ||||
object Specify the items that are pending. | |||||
| |||||
object Specify the items that have arrived. Only for tasks of type delivery | |||||
| |||||
| roundName | string Specify the name of the round where the task is assigned | ||||
| sequence | integer Specify the sequence of the task in the round | ||||
Responses
Response Schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "updatedTime": "2019-08-24T14:15:22Z",
- "updateType": "barcode",
- "pending": {
- "total": true,
- "items": [
- "1111111"
]
}, - "arrived": {
- "total": true,
- "items": [
- "1111111"
]
}, - "roundName": "R01",
- "sequence": 1
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
path Parameters
| extTrackId required | string (ExtTrackId) Example: ext-12345 The extTrackId of the task |
Request Body schema: application/json
| updatedTime | string <date-time> (CarrierTaskStatusUpdatedTime) The date-time of the operation in ISO date format | ||||
| updateType | string (CarrierTaskStatusUpdateType) Enum: "id" "barcode" "total" Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all. | ||||
object Specify the items that are pending. Only for tasks of type pickup | |||||
| |||||
object Specify the items that are departed. Only for tasks of type delivery | |||||
| |||||
object Specify the items that are missing. Only for tasks of type delivery | |||||
| |||||
Responses
Response Schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "updatedTime": "2019-08-24T14:15:22Z",
- "updateType": "barcode",
- "pending": {
- "total": true,
- "items": [
- "1111111"
]
}, - "departed": {
- "total": true,
- "items": [
- "1111111"
]
}, - "missing": {
- "total": true,
- "items": [
- "1111111"
]
}
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
path Parameters
| extTrackId required | string (ExtTrackId) Example: ext-12345 The extTrackId of the task. |
Request Body schema: application/json
| updatedTime | string <date-time> (CarrierTaskStatusUpdatedTime) The date-time of the operation in ISO date format | ||||||||||||||||
| updateType | string (CarrierTaskStatusUpdateType) Enum: "id" "barcode" "total" Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all. | ||||||||||||||||
object Specify the items that are delivered. Only for tasks of type delivery | |||||||||||||||||
| |||||||||||||||||
object Specify the items that are not delivered. Only for tasks of type delivery | |||||||||||||||||
| |||||||||||||||||
object Specify the items that are picked up. Only for tasks of type pickup | |||||||||||||||||
| |||||||||||||||||
object Specify the items that are not picked up. Only for tasks of type pickup | |||||||||||||||||
| |||||||||||||||||
object (CarrierTaskStatusPosition) Position of the driver at the moment of the task completion | |||||||||||||||||
| |||||||||||||||||
| collectedAmount | number (CollectedAmount) >= 0 The amount of money the driver collected while delivering the goods | ||||||||||||||||
object (Metadata) A general-purpose mechanism to store additional data. At the task level, metadata can be made explicit with a base schema in order to push or capture information during the execution of the task. Ask for support if you believe this can enhance your use case. Note: New metadata are merged with the existing one when updating a task | |||||||||||||||||
| |||||||||||||||||
Responses
Response Schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "updatedTime": "2019-08-24T14:15:22Z",
- "updateType": "barcode",
- "delivered": {
- "total": true,
- "items": [
- "1111111"
], - "comment": "I am satisfied with the delivery service",
}, - "notDelivered": {
- "total": true,
- "items": [
- "1111111"
],
}, - "pickedUp": {
- "total": true,
- "items": [
- "1111111"
], - "comment": "I am satisfied with the delivery service",
}, - "notPickedUp": {
- "total": true,
- "items": [
- "1111111"
],
}, - "position": {
- "latitude": 50.824853,
- "longitude": 4.365968
}, - "collectedAmount": 10.2,
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
path Parameters
| extTrackId required | string (ExtTrackId) Example: ext-12345 The extTrackId of the task. |
Request Body schema: application/json
| updatedTime | string <date-time> (CarrierTaskStatusUpdatedTime) The date-time of the operation in ISO date format | ||||
| updateType | string (CarrierTaskStatusUpdateType) Enum: "id" "barcode" "total" Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all. | ||||
object Specify the items that are returned | |||||
| |||||
Responses
Response Schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "updatedTime": "2019-08-24T14:15:22Z",
- "updateType": "barcode",
- "returned": {
- "total": true,
- "items": [
- "1111111"
]
}
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
path Parameters
| extTrackId required | string (ExtTrackId) Example: ext-12345 The extTrackId of the task. |
Request Body schema: application/json
required | object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | ||||
| |||||
Responses
Response Schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "brandingTemplate": "string"
}set task as READY_TO_COLLECT
This endpoint allows you to mark a task as ready to collect
Authorizations:
path Parameters
| extTrackId required | string (ExtTrackId) Example: ext-12345 The extTrackId of the task. |
Request Body schema: application/json
| updatedTime | string <date-time> (CarrierTaskStatusUpdatedTime) The date-time of the operation in ISO date format | ||||||||||||||||
| updateType | string (CarrierTaskStatusUpdateType) Enum: "id" "barcode" "total" Specify how to identify the items to update. If id or barcode is selected then the field items must be used otherwise the field total will specify the transition for all. | ||||||||||||||||
object Specify the items that are dropped. | |||||||||||||||||
| |||||||||||||||||
Responses
Response Schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "updatedTime": "2019-08-24T14:15:22Z",
- "updateType": "barcode",
- "dropped": {
- "total": true,
- "items": [
- "1111111"
], - "comment": "I am satisfied with the delivery service",
}
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
path Parameters
| extTrackId required | string (ExtTrackId) Example: ext-12345 The extTrackId of the task. |
Request Body schema: application/json
object The time window during which the task should be completed. | |||||
| |||||
| excludeFromTimeslot | boolean Default: false If the task uses timeslots, send true to schedule the task out of the existing timeslots, so, the task won't be assigned to any timeslot and the capacity won't be decreased. | ||||
Responses
Response Schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T16:34:56.012Z"
}, - "excludeFromTimeslot": false
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "brandingTemplate": "string"
}Update tracking information
This endpoint allows you to update the live tracking information for multiple tasks delivered in the same round.
Authorizations:
Request Body schema: application/json
| when required | string <date-time> <= 27 characters The date and time when the location information was registered provided in ISO 8601 date format. | ||||||||
object Driver location. This value is only accepted when the task is ONGOING. | |||||||||
| |||||||||
required | Array of objects [ 1 .. 200 ] items Tasks to update in batch. The maximum accepted is 200. | ||||||||
Array ([ 1 .. 200 ] items)
| |||||||||
Responses
Response Schema: application/json
| 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. | |||||
| |||||
Response Schema: application/json
| code | number |
| message | string The reason of failure |
Request samples
- Payload
{- "when": "2019-03-13T12:34:56Z",
- "position": {
- "longitude": 4.365968,
- "latitude": 50.824853,
- "accuracy": 16.88804280209332,
- "altitude": 123.4
}, - "tasks": [
- {
- "extTrackId": "ext-12345",
- "eta": "2019-03-13T14:34:56Z",
- "tasksBefore": 15
}
]
}Response samples
- 200
- 400
[- {
- "internalId": "507f191e810c19729de860ea",
- "taskId": "task-001",
- "extTrackId": "ext-12356",
- "success": true,
- "error": {
- "code": 0,
- "message": "string"
}
}
]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:
Responses
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:
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
| id | string The identifier of the hub | ||||||||||||||||||
| externalId | string The external identifier of the hub | ||||||||||||||||||
| name | string The name of the hub | ||||||||||||||||||
object (HubAddress) | |||||||||||||||||||
| |||||||||||||||||||
| 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
- 200
- 400
- 403
[- {
- "id": "656089f24c56490770d1fcb3",
- "externalId": "my_warehouse",
- "name": "My Warehouse",
- "address": {
- "street": "Avenue Louise",
- "number": "251",
- "city": "Brussels",
- "zip": "1050",
- "country": "BE",
- "coordinates": {
- "latitude": 50.824853,
- "longitude": 4.365968
}
}, - "owner": "platform-snake"
}
]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:
path Parameters
| taskId required | string Example: 507f191e810c19729de860ea The task id |
Responses
Response Schema: application/json
| 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) | |||||||||
| |||||||||
| 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) | |||||||||
| |||||||||
| 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
- 200
- 400
- 403
[- {
- "id": "507f191e810c19729de860ea",
- "event": "driver-approaching",
- "contact": {
- "name": "John Smith",
- "phone": "+32 477 99 99 99",
- "language": "fr"
}, - "channel": "SMS",
- "content": "string",
- "status": "Pending",
- "error": {
- "code": 0,
- "message": "string"
}, - "when": "2019-03-13T12:34:56.012Z"
}
]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:
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:
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
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:
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
| _id | string (ID) | ||||||||||||||||||||||||||||||||||||
object A list of dates and times giving the actual real time the driver did the actions for this 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 | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
| 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. | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
| 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 | ||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||
| picture | string The picture of the round overview (Google Maps). Might not be provided. | ||||||||||||||||||||||||||||||||||||
object (UserSummaryId) The user object. Can be null. | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
Array of objects (Stop) | |||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
object (RoundVehicle) | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
Response samples
- 200
[- {
- "_id": "507f191e810c19729de860ea",
- "realInfo": {
- "hasPrepared": "2019-03-03T02:03:05.366Z",
- "hasStarted": "2019-03-03T02:03:05.366Z",
- "hasFinished": "2019-03-03T02:03:05.366Z",
- "preparationTime": 2273,
- "hasLasted": 14935
}, - "name": "string",
- "status": "CREATED",
- "activity": "classic",
- "shift": "string",
- "targetFlux": "string",
- "platform": "507f191e810c19729de860ea",
- "metadata": {
- "exampleKey": "example value"
}, - "labelsAndSkills": [
- "string"
], - "date": "2019-03-13T12:34:56.012Z",
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "hub": {
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}, - "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": [
- "string"
], - "flux": "5c3c63f23b37f30c4fd0240e",
- "id": "507f191e810c19729de860ea",
- "orderDone": 0,
- "senders": [
- {
- "name": "ExoCraft Productions",
- "reference": "5c3c615d3b37f30b3fc0240c",
- "count": 1,
- "_id": "string"
}
], - "picture": "string",
- "driver": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "string"
}, - "stops": [
- {
- "stopType": 0,
- "type": "hub",
- "stopSequence": 1,
- "travelDistance": 0,
- "arriveTime": "2019-03-13T12:34:56.012Z",
- "departTime": "2019-03-13T12:34:56.012Z",
- "parcel": "507f191e810c19729de860ea",
- "sequence": 0,
- "taskId": "string",
- "taskReference": "task-ref-001-d",
- "violationTime": 0,
- "waitTime": 0,
- "serviceTime": 0,
- "travelTime": 0,
- "coordinates": [
- 0
], - "progress": "ANNOUNCED",
- "status": "ARRIVED",
- "closureDate": "2019-03-25T15:50:50.123Z"
}
], - "delay": {
- "time": 1567000,
- "when": "2019-04-01T08:31:05.121Z"
}, - "vehicle": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}
]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:
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. | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
| 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. | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
| 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 | ||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||
| picture | string The picture of the round overview (Google Maps). Might not be provided. | ||||||||||||||||||||||||||||||||||||
object (UserSummaryId) The user object. Can be null. | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
Array of objects (Stop) | |||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
object (RoundVehicle) | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
Response samples
- 200
{- "_id": "507f191e810c19729de860ea",
- "realInfo": {
- "hasPrepared": "2019-03-03T02:03:05.366Z",
- "hasStarted": "2019-03-03T02:03:05.366Z",
- "hasFinished": "2019-03-03T02:03:05.366Z",
- "preparationTime": 2273,
- "hasLasted": 14935
}, - "name": "string",
- "status": "CREATED",
- "activity": "classic",
- "shift": "string",
- "targetFlux": "string",
- "platform": "507f191e810c19729de860ea",
- "metadata": {
- "exampleKey": "example value"
}, - "labelsAndSkills": [
- "string"
], - "date": "2019-03-13T12:34:56.012Z",
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "hub": {
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}, - "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": [
- "string"
], - "flux": "5c3c63f23b37f30c4fd0240e",
- "id": "507f191e810c19729de860ea",
- "orderDone": 0,
- "senders": [
- {
- "name": "ExoCraft Productions",
- "reference": "5c3c615d3b37f30b3fc0240c",
- "count": 1,
- "_id": "string"
}
], - "picture": "string",
- "driver": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "string"
}, - "stops": [
- {
- "stopType": 0,
- "type": "hub",
- "stopSequence": 1,
- "travelDistance": 0,
- "arriveTime": "2019-03-13T12:34:56.012Z",
- "departTime": "2019-03-13T12:34:56.012Z",
- "parcel": "507f191e810c19729de860ea",
- "sequence": 0,
- "taskId": "string",
- "taskReference": "task-ref-001-d",
- "violationTime": 0,
- "waitTime": 0,
- "serviceTime": 0,
- "travelTime": 0,
- "coordinates": [
- 0
], - "progress": "ANNOUNCED",
- "status": "ARRIVED",
- "closureDate": "2019-03-25T15:50:50.123Z"
}
], - "delay": {
- "time": 1567000,
- "when": "2019-04-01T08:31:05.121Z"
}, - "vehicle": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}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:
Request Body schema: application/json
| roundName | string <string> The round name to create. example: | ||||||||||||
| date | string <date> The day to create the round. If omitted, the system will try to use the date given in example: | ||||||||||||
| 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 When omitted, the system will try to use the example: | ||||||||||||
| 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 When omitted, the system will try to use the example: | ||||||||||||
| driver | string <string> Use the This value is optional unless you use a stop of type | ||||||||||||
| vehicle | string <string> Use the vehicle name to assign a specific vehicle to the round. This value is optional. example: | ||||||||||||
| hub | string <string> Use This value is mandatory if you use a stop of type hub. example: | ||||||||||||
Array of objects The ordered list of stops to include in the round. | |||||||||||||
Array
| |||||||||||||
Responses
Response Schema: application/json
| 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
| |||||||
| 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
- Payload
[- {
- "roundName": "ROUND_FROM_HUB",
- "date": "2021-02-14",
- "startTime": "2021-02-14T09:00:00.000Z",
- "endTime": "2021-02-14T10:30:00.000Z",
- "hub": "hub_1",
- "stops": [
- {
- "type": "hub",
- "arriveTime": "2021-02-14T09:00:00.000Z"
}, - {
- "type": "pickup",
- "id": "5ffeb8445389a819937a095e",
- "arriveTime": "2021-02-14T09:15:00.000Z"
}, - {
- "type": "break",
- "arriveTime": "2021-02-14T09:30:00.000Z",
- "duration": 15,
- "location": [
- 48.8583701,
- 2.2922926
]
}, - {
- "type": "delivery",
- "id": "5ffeb8445389a819937a095f",
- "arriveTime": "2021-02-14T10:00:00.000Z"
}, - {
- "type": "hub",
- "arriveTime": "2021-02-14T10:30:00.000Z"
}
]
}, - {
- "roundName": "ROUND_FROM_DRIVER'S_HOME",
- "date": "2021-02-14",
- "startTime": "2021-02-14T08:45:00.000Z",
- "endTime": "2021-02-14T14:00:00.000Z",
- "stops": [
- {
- "type": "driver",
- "arriveTime": "2021-02-14T08:45:00.000Z"
}, - {
- "type": "pickup",
- "taskId": 11223344,
- "arriveTime": "2021-02-14T09:15:00.000Z"
}, - {
- "type": "break",
- "arriveTime": "2021-02-14T09:30:00.000Z",
- "duration": 15,
- "location": [
- 48.8583701,
- 2.2922926
]
}, - {
- "type": "delivery",
- "taskId": 11223344,
- "arriveTime": "2021-02-14T10:00:00.000Z"
}, - {
- "type": "driver",
- "arriveTime": "2021-02-14T14:00:00.000Z"
}
]
}, - {
- "roundName": "ROUND_FROM_FIRST_AND_LAST_TASK",
- "date": "2021-02-14",
- "startTime": "2021-02-14T08:30:00.000Z",
- "endTime": "2021-02-14T11:30:00.000Z",
- "stops": [
- {
- "type": "pickup",
- "id": "5ffeb8445389a819937a096a",
- "arriveTime": "2021-02-14T08:30:00.000Z"
}, - {
- "type": "break",
- "arriveTime": "2021-02-14T09:30:00.000Z",
- "duration": 15,
- "location": [
- 48.8583701,
- 2.2922926
]
}, - {
- "type": "delivery",
- "id": "5ffeb8445389a819937a096b",
- "arriveTime": "2021-02-14T11:30:00.000Z"
}
]
}, - {
- "roundName": "INVALID_ROUND_EXAMPLE_DATE",
- "date": "1970-01-01",
- "startTime": "1970-01-01T08:00:00.000Z",
- "endTime": "1970-01-01T12:00:00.000Z",
- "stops": [
- {
- "type": "pickup",
- "id": "5ffeb8445389a819937a096c",
- "arriveTime": "2021-02-14T08:30:00.000Z"
}, - {
- "type": "break",
- "arriveTime": "2021-02-14T09:30:00.000Z",
- "duration": 15,
- "location": [
- 48.8583701,
- 2.2922926
]
}, - {
- "type": "delivery",
- "id": "5ffeb8445389a819937a096d",
- "arriveTime": "2021-02-14T11:30:00.000Z"
}
]
}, - {
- "roundName": "INVALID_ROUND_EXAMPLE_TASK",
- "date": "2021-02-14",
- "startTime": "2021-02-14T08:30:00.000Z",
- "endTime": "2021-02-14T11:30:00.000Z",
- "stops": [
- {
- "type": "pickup",
- "id": "5ffeb8445389a819937a096c",
- "arriveTime": "2021-02-14T08:30:00.000Z"
}, - {
- "type": "break",
- "arriveTime": "2021-02-14T09:30:00.000Z",
- "duration": 15,
- "location": [
- 48.8583701,
- 2.2922926
]
}, - {
- "type": "delivery",
- "id": "an_invalid_id",
- "arriveTime": "2021-02-14T11:30:00.000Z"
}
]
}
]Response samples
- 200
- 400
[- {
- "round": "ROUND_FROM_HUB",
- "errors": 0,
- "warnings": [ ],
- "orders": [
- "5ffeb8445389a819937a095e",
- "5ffeb8445389a819937a095f"
], - "message": "ROUND_FROM_HUB successfully created."
}, - {
- "round": "ROUND_FROM_DRIVER'S_HOME",
- "errors": 0,
- "warnings": [ ],
- "orders": [
- "5ffeb8445389a819937a095a",
- "5ffeb8445389a819937a09b"
], - "message": "ROUND_FROM_DRIVER'S_HOME successfully created."
}, - {
- "round": "ROUND_FROM_FIRST_AND_LAST_TASK",
- "errors": 0,
- "warnings": [ ],
- "orders": [
- "5ffeb8445389a819937a096a",
- "5ffeb8445389a819937a096b"
], - "message": "ROUND_FROM_FIRST_AND_LAST_TASK successfully created."
}, - {
- "round": "INVALID_ROUND_EXAMPLE_DATE",
- "errors": 4,
- "warnings": [
- {
- "code": "000-014",
- "message": "Invalid parameter provided. startTime must be for the current day or in the future",
- "details": [ ]
}, - {
- "code": "000-014",
- "message": "Invalid parameter provided. endTime must be for the current day or in the future",
- "details": [ ]
}, - {
- "code": "000-014",
- "message": "Invalid parameter provided. arriveTime for the first order must be filled with the same value as the round startTime",
- "details": [
- "arriveTime of the first stop must have the same value than the round startTime."
]
}, - {
- "code": "000-014",
- "message": "Invalid parameter provided. arriveTime for the last order must be filled with the same value as the round endTime",
- "details": [
- "arriveTime of the last stop must have the same value than the round endTime."
]
}
], - "message": "INVALID_ROUND_EXAMPLE_DATE creation aborted. Please check data."
}, - {
- "round": "INVALID_ROUND_EXAMPLE_TASK",
- "errors": 1,
- "warnings": [
- {
- "code": "001-003",
- "message": "Task Does Not Exist: The task:'an_invalid_id' could not be found in database.",
- "details": [ ]
}
], - "message": "INVALID_ROUND_EXAMPLE_TASK creation aborted. Please check data."
}
]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:
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
- 200
{- "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:
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
| |||||||||||
Response samples
- 200
{- "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": [
- {
- "id": "string",
- "weightInKg": 0,
- "defaultWeightUsed": true,
- "co2Emission": 0,
- "accuracy": "string"
}
]
}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:
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:
Request Body schema: application/json
| 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
- Payload
[- {
- "roundId": "5ffeb8445389a819937a095f",
- "name": "newRoundName1"
}, - {
- "roundId": "5ffeb8445389a819937a096b",
- "name": "newRoundName2"
}
]Shift rounds start time
Shift rounds start time. Only 100 rounds can be updated per request.
Authorizations:
Request Body schema: application/json
| 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
- Payload
[- {
- "roundId": "5ffeb8445389a819937a095f",
- "startTime": "1970-01-01T08:00:00.000Z"
}, - {
- "roundId": "5ffeb8445389a819937a096b",
- "startTime": "1970-01-01T10:30:00.000Z"
}
]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:
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 |
| 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
| _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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskDriver) The driver of the task. It is an Urbantz user. Can be null. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskAlert) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 (TaskReturnedProductsArray) An array containing a list of the returned products for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Response samples
- 200
[- {
- "_id": "507f191e810c19729de860ea",
- "zone": "string",
- "trackingId": "abcdef-123456-4abc-acbacbfcabcfbcbfbacbfab",
- "type": "delivery",
- "taskId": "my-task-id",
- "taskReference": "task-ref-001-d",
- "progress": "ANNOUNCED",
- "status": "ARRIVED",
- "items": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "updated": "2019-03-24T12:34:56.123Z",
- "when": "2019-03-24T12:34:56.123Z",
- "targetFlux": "56fe250f1eb3571100bb081c_MORNING_57454b1556950a11005189fa_2017-11-15",
- "skills": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "sequence": 1,
- "id": "5c98f80a6b3dc61664c05cbb",
- "flux": "5c3c63c23c32c30cb3cc1234c",
- "collectedAmount": 10.2,
- "closureDate": "2019-03-25T15:50:50.123Z",
- "by": "5c3c63c23c32c30cb3cc1234c",
- "attempts": 0,
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "arriveTime": "2019-03-25T15:50:50.123Z",
- "announcement": "507f191e810c19729de860ea",
- "shift": "string",
- "serviceTime": 5,
- "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}, - "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "alert": {
- "when": "2019-03-13T12:34:56.012Z",
- "solved": "2019-03-13T12:34:56.012Z",
- "data": { }
}, - "service": "B2B",
- "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "returnedProducts": [
- {
- "_id": "507f191e810c19729de860ea",
- "barcode": "5410078235370",
- "description": "Soft",
- "name": "Coca Cola zero SG 20clx24",
- "productId": "001234",
- "type": "Food",
- "unitPrice": 13.95,
- "quantity": 3
}
]
}
]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:
Request Body schema: application/json
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| carrier | string <= 128 characters Identifier of the carrier to which the task will be associated. If the identifier is not valid, the task won't be associated to any carrier. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| client | string The value provided here will depend on the option selected in the flow configuration.
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. Any other value provided is ignored. This feature is only available when using HERE optimizer. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer >= 1 Sequence of the task in the round. To be used in combination with positionInRound (ordered) or round (when using preset rounds) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
required | object (AnnounceTaskAddress) Address of the task | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (AnnounceTaskProductsArray) A list of products that the delivery will include | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Metadata) A general-purpose mechanism to store additional data. At the task level, metadata can be made explicit with a base schema in order to push or capture information during the execution of the task. Ask for support if you believe this can enhance your use case. Note: New metadata are merged with the existing one when updating a task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Collect) The click and collect information | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeslotReservationId | string (TimeslotReservationId) Internal identifier to associate a task to a timeslot reservation | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| priority | number >= 0 Priority can influence the result optimization. In case not all of the tasks can fit in the round(s), the tasks with a higher priority are more likely to be included than the ones with lower priority. The higher the number, the higher the priority of the task will be. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
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
- Payload
[- {
- "type": "delivery",
- "taskId": "my-task-id",
- "taskReference": "task-ref-001-d",
- "items": [
- {
- "type": "string",
- "name": "string",
- "description": "string",
- "barcode": "string",
- "barcodeEncoding": "CODE128",
- "reference": "string",
- "quantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "hasBeenPaid": false,
- "notificationSettings": {
- "sms": false,
- "email": false
}, - "carrier": "string",
- "client": "00014",
- "collectedAmount": 0,
- "price": 0,
- "round": "R01",
- "positionInRound": "ordered",
- "sequence": 1,
- "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "date": "2019-03-13T12:34:56.012Z",
- "serviceTime": 5,
- "maxTransitTime": 0,
- "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "address": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "BE",
- "longitude": 4.365968,
- "latitude": 50.824853,
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
]
}, - "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "categories": [
- "B2B"
], - "collect": {
- "activated": true,
- "point": "point1",
- "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}
}, - "timeslotReservationId": "string",
- "priority": 0
}
]Response samples
- 200
- 400
- 403
{- "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:
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. Any other value provided is ignored. This feature is only available when using HERE optimizer. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer >= 1 Sequence of the task in the round. To be used in combination with positionInRound (ordered) or round (when using preset rounds) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| labels | Array of strings (TaskLabels) Labels the vehicle must have to execute the task. They are calculated from the items. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| instructions | string (Instructions) <= 1024 characters Extra information for the driver to reach the destination | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Metadata) A general-purpose mechanism to store additional data. At the task level, metadata can be made explicit with a base schema in order to push or capture information during the execution of the task. Ask for support if you believe this can enhance your use case. Note: New metadata are merged with the existing one when updating a task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (UpdateTaskAddress) Address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Collect) The click and collect information | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskReturnedProductsArray) An array containing a list of the returned products for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "taskId": "my-task-id",
- "taskReference": "task-ref-001-d",
- "paymentType": "CCOD",
- "skills": [
- "speaks_french"
], - "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "positionInRound": "ordered",
- "sequence": 1,
- "collectedAmount": 0,
- "serviceTime": 5,
- "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "address": "251 avenue louise, 1050 Brussels, Belgium",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "countryCode": "BEL"
}, - "hasBeenPaid": false,
- "price": 0,
- "items": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "categories": [
- "B2B"
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "collect": {
- "activated": true,
- "point": "point1",
- "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}
}, - "returnedProducts": [
- {
- "_id": "507f191e810c19729de860ea",
- "barcode": "5410078235370",
- "description": "Soft",
- "name": "Coca Cola zero SG 20clx24",
- "productId": "001234",
- "type": "Food",
- "unitPrice": 13.95,
- "quantity": 3
}
], - "priority": 0,
- "brandingTemplate": "string",
- "recalculateServiceTime": false
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. Any other value provided is ignored. This feature is only available when using HERE optimizer. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer >= 1 Sequence of the task in the round. To be used in combination with positionInRound (ordered) or round (when using preset rounds) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| labels | Array of strings (TaskLabels) Labels the vehicle must have to execute the task. They are calculated from the items. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| instructions | string (Instructions) <= 1024 characters Extra information for the driver to reach the destination | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Metadata) A general-purpose mechanism to store additional data. At the task level, metadata can be made explicit with a base schema in order to push or capture information during the execution of the task. Ask for support if you believe this can enhance your use case. Note: New metadata are merged with the existing one when updating a task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (UpdateTaskAddress) Address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Collect) The click and collect information | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskReturnedProductsArray) An array containing a list of the returned products for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| brandingTemplate | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Request samples
- Payload
{- "taskId": "my-task-id",
- "taskReference": "task-ref-001-d",
- "paymentType": "CCOD",
- "skills": [
- "speaks_french"
], - "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "positionInRound": "ordered",
- "sequence": 1,
- "collectedAmount": 0,
- "serviceTime": 5,
- "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "address": "251 avenue louise, 1050 Brussels, Belgium",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "countryCode": "BEL"
}, - "hasBeenPaid": false,
- "price": 0,
- "items": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "categories": [
- "B2B"
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "collect": {
- "activated": true,
- "point": "point1",
- "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}
}, - "returnedProducts": [
- {
- "_id": "507f191e810c19729de860ea",
- "barcode": "5410078235370",
- "description": "Soft",
- "name": "Coca Cola zero SG 20clx24",
- "productId": "001234",
- "type": "Food",
- "unitPrice": 13.95,
- "quantity": 3
}
], - "priority": 0,
- "brandingTemplate": "string",
- "recalculateServiceTime": false
}Response samples
- 200
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object A second time window during which the task can be completed. It cannot be modified once the task is assigned to a round. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (GeocodedAddress) Geocoded address of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (SourceAddress) Address provided at announcement | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasBeenPaid | boolean Indicates if the task has been paid by the recipient | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| price | number >= 0 The price of the task (basket price for e-commerce) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| driver | string The identifier of the driver (urbantz user) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Requirements) Required actions in the mobile application. It cannot be modified once the task is assigned to a round | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskExecution) Information collected by the driver during the execution of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (TaskLog) Log of the progress transition of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| categories | Array of strings (Categories) Categories are labels assigned to tasks. They can be used to collect delivery preferences in the tracking page or to show information on the driver app as icons. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object Information about contactless delivery | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object If there are assets to picked up or to be left at the client | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of file attachments (pictures, delivery notes, etc...) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
- 200
- 400
{- "createdBy": {
- "firstName": "John",
- "lastName": "Doe",
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "externalId": "extRefDoe"
}, - "__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": [
- {
- "_id": "507f191e810c19729de860ea",
- "type": "Box",
- "status": "ARRIVED",
- "name": "Soft Drink 6 pack",
- "description": "Big box with a red mark on the top",
- "barcode": 9876543211234,
- "barcodeEncoding": "CODE128",
- "reference": 9876543211234,
- "quantity": 1,
- "processedQuantity": 1,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "damaged": {
- "confirmed": false,
- "pictures": [
- "string"
]
}, - "labels": [
- "frozen"
], - "skills": [
- "speaks_french"
], - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "PENDING",
- "by": "string"
}
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "group": "string"
}
], - "client": "507f191e810c19729de860ea",
- "hub": "507f191e810c19729de860ea",
- "hubName": "My Warehouse",
- "associatedName": "Lumikko Oyj",
- "associated": "5c3c63c23c32c30cb3cc1234c",
- "dependency": "507f191e810c19729de860ea",
- "hasDependency": "507f191e810c19729de860ea",
- "round": "R01",
- "archived": true,
- "actualTime": {
- "arrive": {
- "when": "2019-03-24T12:34:56.123Z",
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}, - "forced": false,
- "isCorrectAddress": false
}
}, - "order": "string",
- "paymentType": "CCOD",
- "platform": "5c98f80a6b3dc61664c05cbf",
- "platformName": "Cortedal SYS, Oy",
- "endpoint": "5c3c645e3b37f30b3fc0240f",
- "errorLocation": {
- "addressLines": [
- "string"
], - "geocodeScore": 98,
- "location": {
- "type": "Point",
- "geometry": [
- 0
]
}
}, - "customerCalls": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "by": "string"
}
], - "issues": [
- {
- "type": "GEOCODING",
- "code": 0,
- "line": 0,
- "error": "string"
}
], - "notifications": [
- {
- "notificationId": "string",
- "sentDate": "2019-12-23T12:34:56.123Z",
- "by": {
- "firstName": "John",
- "lastName": "Doe",
- "phoneNumber": "32123123123",
- "picture": "/some/folder/image/c1235b6a253cd12d3",
- "_id": "507f191e810c19729de860ea",
- "externalId": "string"
}
}
], - "notificationSettings": {
- "sms": false,
- "email": false
}, - "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": [
- "speaks_french"
], - "roundName": "R03",
- "roundColor": "#FFCC0D",
- "products": [
- {
- "productId": "001234",
- "name": "CHEESE",
- "description": "Goat cheese pack, 400gr",
- "type": "food",
- "barcode": "11231212121",
- "quantity": 3,
- "unitPrice": 13.95,
- "isSubstitution": false,
- "quantityRejected": 0,
- "rejectedReason": {
- "_id": "507f191e810c19729de860ea",
- "name": "damaged"
}
}
], - "hasRejectedProducts": false,
- "activity": "string",
- "positionInRound": "ordered",
- "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": {
- "serviceTime": 120,
- "tasksDeliveredInSameStop": 1,
- "confidence": "HIGH",
- "version": 2
}, - "maxTransitTime": 0,
- "timeWindowMargin": 0,
- "stopSequence": 2,
- "date": "2019-03-13T12:34:56.012Z",
- "labels": [
- "frozen"
], - "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "metadata": {
- "property1": 23,
- "property2": "Hello World"
}, - "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "timeWindow2": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "contact": {
- "account": "ACC123456789",
- "name": "Acme Inc.",
- "person": "Luke Skywalker",
- "phone": "+32 477 99 99 99",
- "extraPhones": [
- "+32 477 99 99 99"
], - "language": "fr",
- "buildingInfo": {
- "floor": 5,
- "hasElevator": true,
- "digicode1": "1234A",
- "digicode2": "4321A",
- "hasInterphone": true,
- "interphoneCode": "4524#"
}
}, - "location": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "country": "Belgium",
- "countryCode": "BEL",
- "address": "251 avenue louise, 1050 Brussels, Belgium",
- "geocodeScore": 98,
- "origin": "ADDRESS_BOOK",
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}
}, - "source": {
- "building": "Bâtiment A",
- "number": "251b",
- "street": "Avenue Louise",
- "city": "Brussels",
- "zip": "1050",
- "addressLines": [
- "251 Avenue Louise",
- "1050 Brussels",
- "Belgium"
], - "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "country": "Belgium"
}, - "hasBeenPaid": false,
- "price": 0,
- "driver": "5c98f80a6b3dc61664c05cbb",
- "requires": {
- "pickup": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "signature": false,
- "signatureAndComment": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "delivery": {
- "dispatcher": {
- "scan": false
}, - "driver": {
- "contactless": false,
- "prepCheckList": false,
- "prepScan": false,
- "signature": false,
- "signatureAndComment": false,
- "signatureAndItemConcerns": false,
- "scan": false,
- "comment": false,
- "photo": false
}, - "stop": {
- "onSite": false
}, - "failure": {
- "photo": false
}
}, - "other": {
- "driver": {
- "timer": false
}
}
}, - "execution": {
- "successComment": "string",
- "successPicture": "string",
- "failedReason": {
- "reasonId": "507f191e810c19729de860ea",
- "reason": "string",
- "custom": "string",
- "picture": "string"
}, - "timer": {
- "timestamps": [
- {
- "type": "start",
- "time": "2019-12-23T12:34:56.123Z"
}
]
}, - "signature": {
- "data": "string",
- "name": "string"
}, - "position": {
- "accuracy": 16.88804280209332,
- "altitude": 93.19367065219194,
- "heading": 90,
- "latitude": 50.824853,
- "longitude": 4.365968,
- "speed": 42.5,
- "timestamp": 1553529404789
}, - "contactless": {
- "forced": true,
- "reason": "string"
}
}, - "log": [
- {
- "_id": "507f191e810c19729de860ea",
- "when": "2019-03-13T12:34:56.012Z",
- "to": "ANNOUNCED",
- "by": "string"
}
], - "categories": [
- "B2B"
], - "contactless": {
- "pin": 7270
}, - "assets": {
- "deliver": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
], - "return": [
- {
- "assetId": "string",
- "name": "string",
- "price": 0,
- "amount": 0
}
]
}, - "attachments": [
- {
- "_id": "5f9af33b4f8cc32e047d83b2",
- "name": "Delivery Note",
- "url": "/attachments/tasks/5c3c63c23c32c30cb3cc1234c/af6227d6-f915-4924-8873-98da8131df3a.pdf"
}
], - "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:
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __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://tracking.urbantz.com/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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | boolean 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects The list of calls recorded by the driver | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects Issues occurred during the announcement of the task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects List of manual SMS notifications sent to the recipient | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TaskNotificationSettings) Notification settings for this task | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hasRejectedProducts | boolean Default: false If the task has one or more rejected products | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| activity | string (TaskInternalField) For internal use only. Please do not use. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| positionInRound | string Enum: "first" "last" "ordered" When provided, the task will be placed at the position requested in the round. The values accepted are “first”, “last”, “ordered”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| sequence | integer (TaskSequence) >= 1 Sequence of the task in the round | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| id | string The id of the task. If | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. If it is modified after the task has been inserted into a round, it will not update or affect the duration of the round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RealServiceTime) It is the time the driver spent at the delivery address since parking the vehicle to departure that Urbantz calculated based on the data received when the round is completed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| imagePath | string The base path for images of this task. You can concatenate this URI (if provided) with, for instance, the content of 'execution.signature.data' to obtain the signature. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| maxTransitTime | integer (MaxTransitTime) >= 0 The maximum transit time in minutes. The transit time is the duration from the departure time of the pickup to the arrival time at the delivery. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeWindowMargin | number >= 0 Default: 0 A margin in minutes to the time window which is deemed acceptable | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| stopSequence | number The stop sequence number for this task, in the related round. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| date | string <date-time> 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Dimensions) An object of key-value pairs where the key represents the dimension type (such as weight or volume) and the value the corresponding dimensional value. For the keys, only dimensions which have been defined on the Platform can be used. For values, up to 6 decimals are taken into account, extra decimals are truncated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object The time window during which the task should be completed. It cannot be modified once | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||