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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. 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 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. 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 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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. 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 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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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": "first",
- "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"
}Replan a task (id)
Replan the failed tasks to another day and time slot. The task must be COMPLETED, and all the items in it must be not delivered or not picked up.
Authorizations:
path Parameters
| id required | string (ID) Example: 507f191e810c19729de860ea The database ID the task to replan. |
Request Body schema: application/json
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||
| |||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||
| |||||
Responses
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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. |
Request samples
- Payload
{- "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"
}
}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": "first",
- "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"
}Replan a task (TaskId)
Replan the failed tasks to another day and time slot. The task must be COMPLETED, and all the items in it must be not delivered or not picked up.
Authorizations:
path Parameters
| taskId required | string (TaskId) Example: my-task-id The taskId of the task to replan. |
Request Body schema: application/json
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||
| |||||
object (TimeWindow) The time window during which the task should be completed. This field is required if there's a type specified. It cannot be modified once the task is assigned to a round | |||||
| |||||
Responses
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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. |
Request samples
- Payload
{- "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"
}
}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": "first",
- "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"
}Receive a task (id)
Put a task to receive
Authorizations:
path Parameters
| id required | string (ID) Example: 507f191e810c19729de860ea The database ID the task to receive. |
Request Body schema: application/json
Array of objects | |||||
Array
| |||||
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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. |
Request samples
- Payload
{- "items": [
- {
- "_id": "string",
- "processedQuantity": 1
}
]
}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": "first",
- "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"
}Retrieve tracking information
Fetches tracking information about a specific task, based on its internal identifier or its taskId.
The maximum number of requests for this endpoint is 3600 requests per minute.
Authorizations:
query Parameters
| internalId | string (ID) Example: internalId=507f191e810c19729de860ea The tasks internal id to search for |
| taskId | string (TaskId) Example: taskId=my-task-id The taskId to search for |
Responses
Response Schema: application/json
| _id | string (InternalTaskID) Internal ID of the task. You should use this identifier for other API calls. |
| 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. |
| extTrackId | string (ExtTrackId) An external task identifier to use for mapping data between an external carrier and Urbantz |
| eta | string <date-time> Is null if task is not inside a round or if task is COMPLETED. |
| taskStatus | string (TaskStatus) Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED" Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage |
| closureDate | string <date-time> (ClosureDate) The date and time the task was completed (in ISO 8601 format) |
| driverLocation | Array of numbers Respectively last know longitude and lattitude. It's null if the task is not inside of an ONGOING round, if the task is COMPLETED or if the round sequences were not respected. |
| precedingTasks | number The number of tasks left to be completed before the task. It's null if the task is not inside of an ONGOING round, if the task is COMPLETED or if the round sequences were not respected. |
Response samples
- 200
[- {
- "_id": "string",
- "taskId": "my-task-id",
- "taskReference": "string",
- "extTrackId": "ext-12345",
- "eta": null,
- "taskStatus": "PENDING",
- "closureDate": null,
- "driverLocation": null,
- "precedingTasks": null
}, - {
- "_id": "string",
- "taskId": "my-task-id",
- "taskReference": "string",
- "extTrackId": "ext-12345",
- "eta": "2019-03-25T15:50:50.123Z",
- "taskStatus": "DEPARTED",
- "closureDate": null,
- "driverLocation": [
- 2.2945,
- 48.8584
], - "precedingTasks": 2
}, - {
- "_id": "string",
- "taskId": "my-task-id",
- "taskReference": "string",
- "extTrackId": "ext-12345",
- "eta": null,
- "taskStatus": "DELIVERED",
- "closureDate": "2019-03-25T15:55:00.321Z",
- "driverLocation": null,
- "precedingTasks": null
}
]Integrate the scheduling flow in your own online shop with 3 simple steps and connect with multiple carriers with one single and standard entry point.
This API allows to retrieve timeslots in a defined period from multiple carriers and hubs based on the rules previously defined in your platform.
Once a timeslot is selected, the API will communicate the reserved timeslot to the carrier and reserve it internally in Urbantz.
The last step is to confirm the timeslot. In this step the timeslot will be confirmed to the carrier .
Get timeslots
This API allows to retrieve the available timeslots from a specific hub and carrier. You can query for a maximum of 14 days in a single request.
All the data sent in this step will be stored and used in the following steps if it is required.
Authorizations:
header Parameters
| reference | string Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs. |
Request Body schema: application/json
| hubId | string <= 255 characters When using the API to consume timeslots from an external carrier, this field is optional unless stated otherwise by the carrier.
As an alternative, the hub can be selected automatically using the Hub Allocation Rules configured in the Flow. To use these rules, the flow secret must be provided in the request (see Authorization section). | ||||||||||||||||||||||||
| carriers | Array of strings[ items <= 128 characters ] | ||||||||||||||||||||||||
| start required | string <date-time> <= 27 characters Search for timeslots from the date defined in ISO 8601 format. A minimal precision to the minutes is required. Seconds and milliseconds can be omitted (they will default to 0). | ||||||||||||||||||||||||
| stop required | string <date-time> <= 27 characters Search for timeslots until the date defined in ISO 8601 format. A minimal precision to the minutes is required. Seconds and milliseconds can be omitted (they will default to 0). The difference between | ||||||||||||||||||||||||
| serviceTime | number [ 0 .. 18000 ] Amount of service time consumed in minutes for the timeslot. | ||||||||||||||||||||||||
| taskId | string <= 256 characters | ||||||||||||||||||||||||
| taskReference | string (TaskReference) <= 256 characters A secondary task identifier to use for mapping data between systems. | ||||||||||||||||||||||||
| type | string Default: "delivery" Enum: "delivery" "pickup" | ||||||||||||||||||||||||
required | object (address) | ||||||||||||||||||||||||
| |||||||||||||||||||||||||
Array of objects (item) <= 1024 items | |||||||||||||||||||||||||
Array (<= 1024 items)
| |||||||||||||||||||||||||
object (contact) | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
object (Metadata) A general-purpose mechanism to store additional data. At the task level, metadata can be made explicit with a base schema in order to push or capture information during the execution of the task. Ask for support if you believe this can enhance your use case. Note: New metadata are merged with the existing one when updating a task | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
Responses
Response Schema: application/json
Array of objects | |||||||||||||||||||
Array
| |||||||||||||||||||
| recipientTimeZoneId | string The IANA timezone ID of the recipient address (if specified) | ||||||||||||||||||
Response Schema: application/json
| code | number |
| message | string The reason of failure |
Request samples
- Payload
{- "hubId": "string",
- "carriers": [
- "string"
], - "start": "2021-03-30T09:00Z",
- "stop": "2021-04-10T10:00Z",
- "serviceTime": 18000,
- "taskId": "string",
- "taskReference": "task-ref-001-d",
- "type": "delivery",
- "address": {
- "street": "Avenue Louise",
- "number": "251b",
- "city": "Brussels",
- "country": "BEL",
- "zip": "12345",
- "coordinates": {
- "latitude": 50.824853,
- "longitude": 4.365968
}, - "administrativeLevel1": "string",
- "administrativeLevel2": "string",
- "administrativeLevel3": "string"
}, - "items": [
- {
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "quantity": 1,
- "name": "Soft Drink 6 pack",
- "labels": [
- "string"
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}
}
], - "contact": {
- "account": "1234-ID",
- "firstName": "John",
- "lastName": "Doe",
- "company": "Urbantz",
- "phone": "+32 81 00 00 00",
- "instructions": "the bell is upstairs",
- "buildingInfo": {
- "floor": -200,
- "hasElevator": true
}
}, - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}
}Response samples
- 200
- 400
{- "timeslots": [
- {
- "timeslotId": "string",
- "start": "2019-08-24T14:15:22Z",
- "stop": "2019-08-24T14:15:22Z",
- "hubId": "string",
- "carrier": "string",
- "class": "A",
- "price": 9.99,
- "baselinePrice": 20,
- "sustainabilityScore": 1
}
], - "recipientTimeZoneId": "Europe/Brussels"
}Reserve a timeslot
This API allows to reserve a timeslot using the timeslot id received in Get timeslots.
The reservation will hold the capacity in the timeslot until it is cancelled or expired.
Once the reservation is confirmed the capacity will be blocked permanently.
Authorizations:
header Parameters
| reference | string Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs. |
Request Body schema: application/json
| timeslotId required | string |
| confirm | boolean When this parameter is true, the reservation will be autoconfirmed and it won’t be needed to use /confirm-reservation |
| ttl | number [ 5 .. 1440 ] Default: 120 Time to live of the reservation. If the reservation is not confirmed within this time, it will be cancelled automatically. This value must be provided in minutes and allows a range between 5 minutes and 1440 minutes (24 hours). Default: 120. If a carrier has a hard time to live, the |
Responses
Response Schema: application/json
| reservationId | string |
| carrierReservationId | string |
| isConfirmed | boolean |
| expires | string <date-time> Time when the reservation will expire and therefore be cancelled automatically |
Response Schema: application/json
| code | number |
| message | string The reason of failure |
Request samples
- Payload
{- "timeslotId": "string",
- "confirm": true,
- "ttl": 300
}Response samples
- 200
- 400
{- "reservationId": "string",
- "carrierReservationId": "string",
- "isConfirmed": true,
- "expires": "2023-10-13T05:02:56.148Z"
}Confirm a reservation
This API allows to confirm an existing reservation. Only pending reservations can be confirmed, if the reservation was cancelled it won't be possible to confirm it.
The information sent in this step will be appended to the information sent in get timeslots. In case of data contradictions, the API will return an error.
Authorizations:
header Parameters
| reference | string Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs. |
Request Body schema: application/json
| reservationId required | string <= 128 characters | ||||||||||||||||||||||||
| taskId | string <= 256 characters | ||||||||||||||||||||||||
| taskReference | string (TaskReference) <= 256 characters A secondary task identifier to use for mapping data between systems. | ||||||||||||||||||||||||
| serviceTime | number [ 0 .. 18000 ] Amount of service time consumed in minutes for the timeslot. | ||||||||||||||||||||||||
| type | string Default: "delivery" Enum: "delivery" "pickup" | ||||||||||||||||||||||||
object (address) | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
Array of objects (item) <= 1024 items | |||||||||||||||||||||||||
Array (<= 1024 items)
| |||||||||||||||||||||||||
object (contact) | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
object (Metadata) A general-purpose mechanism to store additional data. At the task level, metadata can be made explicit with a base schema in order to push or capture information during the execution of the task. Ask for support if you believe this can enhance your use case. Note: New metadata are merged with the existing one when updating a task | |||||||||||||||||||||||||
| |||||||||||||||||||||||||
Responses
Response Schema: application/json
Response Schema: application/json
| code | number |
| message | string The reason of failure |
Request samples
- Payload
{- "reservationId": "string",
- "taskId": "string",
- "taskReference": "task-ref-001-d",
- "serviceTime": 18000,
- "type": "delivery",
- "address": {
- "street": "Avenue Louise",
- "number": "251b",
- "city": "Brussels",
- "country": "BEL",
- "zip": "12345",
- "coordinates": {
- "latitude": 50.824853,
- "longitude": 4.365968
}, - "administrativeLevel1": "string",
- "administrativeLevel2": "string",
- "administrativeLevel3": "string"
}, - "items": [
- {
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "quantity": 1,
- "name": "Soft Drink 6 pack",
- "labels": [
- "string"
], - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}
}
], - "contact": {
- "account": "1234-ID",
- "firstName": "John",
- "lastName": "Doe",
- "company": "Urbantz",
- "phone": "+32 81 00 00 00",
- "instructions": "the bell is upstairs",
- "buildingInfo": {
- "floor": -200,
- "hasElevator": true
}
}, - "metadata": {
- "property1": 23,
- "property2": "Hello World"
}
}Response samples
- 200
- 400
{ }Cancel a reservation
The API allows to cancel an existing reservation that wasn't previously cancelled or assigned.
Authorizations:
header Parameters
| reference | string Use this parameter to pass your own reference to the request, to be able to retrieve it later in logs. |
Request Body schema: application/json
| reservationId required | string <= 128 characters |
Responses
Response Schema: application/json
Response Schema: application/json
| code | number |
| message | string The reason of failure |
Request samples
- Payload
{- "reservationId": "string"
}Response samples
- 200
- 400
{ }Retrieve reservation (id)
The API allows to get an existing reservation by its id
Authorizations:
path Parameters
| reservationId required | string Use this parameter to pass the id of the reservation. |
Responses
Response Schema: application/json
| internalReservationId | string <= 255 characters Identifier of the reservation in the carrier's system |
| carrierReservationId | string <= 255 characters Identifier of the reservation in the carrier's system |
| start | string <date-time> ISO 8601 format of the reservation timeslot starting date and hour |
| stop | string <date-time> ISO 8601 format of the reservation timeslot stopping date and hour |
| hub | string Identifier of the hub in the carrier's system |
| status | string Enum: "PENDING" "CONFIRMED" "ASSIGNED" "CANCELLED" |
| task | string The internal id of the task associated with this reservation, if any - can be used in GetTask |
| recipientTimeZoneId | string The IANA timezone ID of the recipient address (if specified) |
| expires | string <date-time> Time when the reservation will expire and therefore be cancelled automatically |
| carrier | string The snake-case identifier of the platform of the carrier |
| cancellationReason | string Enum: "CANCELLED_BY_API" "PURGED" "EXPIRED" "TASK_UNPLANNED" "TASK_UPDATE" Indicates why the reservation has been cancelled |
Response Schema: application/json
| code | number |
| message | string The reason of failure |
Response samples
- 200
- 400
{- "internalReservationId": "6294ab89974c66bf1f8e0ad7",
- "carrierReservationId": "983ba310-c375-4dc4-92fc-3c15813ee9aa",
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-20T12:34:56.012Z",
- "hub": "string",
- "status": "PENDING",
- "task": "Task001",
- "recipientTimeZoneId": "Europe/Brussels",
- "expires": "2023-10-13T05:02:56.148Z",
- "carrier": "carrier-snake",
- "cancellationReason": "CANCELLED_BY_API"
}Retrieve reservations
The API allows to get existing reservations by certain criterias.
Authorizations:
query Parameters
| start required | string <date-time> Example: start=2019-03-13T12:34:56.012Z The lower bound of the date range to search within. The search is based on the start date of the timeslots reserved. It should be provided in ISO (8601) date format. |
| stop required | string <date-time> Example: stop=2019-03-20T12:34:56.012Z The upper bound of the date range to search within. The search is based on the start date of the timeslots reserved. It should be provided in ISO (8601) date format. |
| hubId | string (ID) Example: hubId=507f191e810c19729de860ea The (internal or external) ID of the hub to which the reservation has been assigned to. |
| status | string Enum: "PENDING" "CONFIRMED" "ASSIGNED" "CANCELLED" Example: status=PENDING The status of the reservation. |
| carrier | string Example: carrier=carrier-snake The snake-case identifier of the carrier who has reserved the timeslot. |
| page | number (Page) Default: 0 The page index of the requested records |
| pageSize | number Default: 100 The page size of the requested records |
Responses
Response Schema: application/json
| internalReservationId | string <= 255 characters Identifier of the reservation in the carrier's system |
| carrierReservationId | string <= 255 characters Identifier of the reservation in the carrier's system |
| start | string <date-time> ISO 8601 format of the reservation timeslot starting date and hour |
| stop | string <date-time> ISO 8601 format of the reservation timeslot stopping date and hour |
| hub | string Identifier of the hub in the carrier's system |
| status | string Enum: "PENDING" "CONFIRMED" "ASSIGNED" "CANCELLED" |
| task | string The internal id of the task associated with this reservation, if any - can be used in GetTask |
| recipientTimeZoneId | string The IANA timezone ID of the recipient address (if specified) |
| expires | string <date-time> Time when the reservation will expire and therefore be cancelled automatically |
| carrier | string The snake-case identifier of the platform of the carrier |
| cancellationReason | string Enum: "CANCELLED_BY_API" "PURGED" "EXPIRED" "TASK_UNPLANNED" "TASK_UPDATE" Indicates why the reservation has been cancelled |
Response Schema: application/json
| code | number |
| message | string The reason of failure |
Response samples
- 200
- 400
[- {
- "internalReservationId": "6294ab89974c66bf1f8e0ad7",
- "carrierReservationId": "983ba310-c375-4dc4-92fc-3c15813ee9aa",
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-20T12:34:56.012Z",
- "hub": "string",
- "status": "PENDING",
- "task": "Task001",
- "recipientTimeZoneId": "Europe/Brussels",
- "expires": "2023-10-13T05:02:56.148Z",
- "carrier": "carrier-snake",
- "cancellationReason": "CANCELLED_BY_API"
}
]Tracking endpoints provide the information needed to display a task to the end recipient. This includes information about the task itself, and configuration information around the task, such as theming and platform configurations.
Get task information
Get the information that is specific to a task and its end recipient.
Authorizations:
path Parameters
| trackingId required | string Tracking identifier of the task |
Responses
Response 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. | ||||||||||||||||||||||||||||||||
| 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 | ||||||||||||||||||||||||||||||||
| arriveTime | string <date-time> (TaskArrivalTime) The estimated time of arrival to the delivery location (in ISO 8601 format) | ||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||
| instructions | string (Instructions) <= 1024 characters Extra information for the driver to reach the destination | ||||||||||||||||||||||||||||||||
object (Collect) The click and collect information | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
object (Contact) Information of the recipient of the task | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
object (RealTimeTracking) | |||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||
Response samples
- 200
{- "type": "delivery",
- "taskId": "my-task-id",
- "taskReference": "task-ref-001-d",
- "progress": "ANNOUNCED",
- "status": "ARRIVED",
- "arriveTime": "2019-03-25T15:50:50.123Z",
- "serviceTime": 5,
- "instructions": "Once inside of the building, follow the corridor on the right and take the elevator",
- "collect": {
- "activated": true,
- "point": "point1",
- "timeWindow": {
- "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#"
}
}, - "timeWindow": {
- "start": "2019-03-13T12:34:56.012Z",
- "stop": "2019-03-13T12:34:56.012Z"
}, - "location": {
- "location": {
- "geometry": [
- 0
], - "type": "Point"
}, - "addressLines": [
- "string"
], - "number": "string",
- "street": "string",
- "city": "string",
- "zip": "string",
- "country": "string",
- "address": "string",
- "origin": "string"
}, - "driver": {
- "firstName": "string",
- "lastName": "string",
- "picture": "string"
}, - "review": {
- "rating": 0,
- "comment": "string",
- "when": "2019-03-13T12:34:56.012Z"
}, - "surveyAnswers": {
- "FieldName1": "Answer1",
- "FieldName2": "Answer2"
}, - "realTimeTracking": {
- "driverLocation": [
- 2.2945,
- 48.8584
], - "precedingTasks": 0,
- "eta": "1029-03-30T12:23:34.456Z"
}
}Get the platform configurations of the task
Get the platform configuration information that is relevant for displaying a task to the end recipient. This includes configurations such as theming and rating preferences, for example.
Authorizations:
path Parameters
| trackingId required | string Tracking identifier of the task |
Responses
Response Schema: application/json
| mapAvailability | number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| limitEtaToTimewindow | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| showDriver | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| showFailedDeliveryReason | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| showTasksBeforeMe | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| showLocationDetails | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| tasksBeforeMeThreshold | number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timeDisplayMode | string Enum: "TIME_WINDOW" "ETA" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (PlatformTheme) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (SurveyQuestion) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (TrackingPlatformFeatures) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||
Response samples
- 200
{- "mapAvailability": 0,
- "limitEtaToTimewindow": true,
- "showDriver": true,
- "showFailedDeliveryReason": true,
- "showTasksBeforeMe": true,
- "showLocationDetails": true,
- "tasksBeforeMeThreshold": 0,
- "timeDisplayMode": "TIME_WINDOW",
- "theme": {
- "primaryColor": "#c01616",
- "secondaryColor": "#c01616",
- "backgroundColor": "#c01616",
- "backgroundColor2": "#c01616",
- "backgroundPicture": "pic.png",
- "adPicture": "pic.png",
- "logo": "pic.png",
- "email": "john.doe@urbantz",
- "phone": "+32 477 99 99 99",
}, - "endpoint": {
- "planning": {
- "enabled": true,
- "allowFromTrackingPage": true,
- "numberOfDays": 0,
- "numberOfReplanings": 0,
- "isMaximumDaysReplaningsEnabled": true,
- "isMaximumNumberReplaningsEnabled": true,
- "from": 0,
- "to": 0,
- "flexibleTimewindows": true,
- "ignoreCapacityConstraint": true
}
}, - "surveyQuestions": [
- {
- "category": "string",
- "description": [
- {
- "lang": "en-001",
- "text": "translated text"
}
], - "enum": [
- "Val1",
- "Val2",
- "Val3"
], - "max": 0,
- "min": 0,
- "name": "string",
- "providedOn": "string",
- "type": "text"
}
], - "categoriesQuestions": {
- "enabled": true,
- "questions": [
- {
- "textContent": "string",
- "type": "single"
}
]
}, - "failedReasons": [
- {
- "name": "string",
- "description": [
- {
- "lang": "string",
- "text": "string"
}
]
}
], - "features": {
- "driverRatings": true,
- "trackingSurvey": true
}, - "trustPilot": {
- "enabled": true,
- "tagByStatus": true,
- "minStars": 0,
- "customTags": [
- "string"
]
}, - "timeslots": [
- {
- "generatedTimeslots": [ ],
- "timeslotRuleVersion": "string",
- "timeWindow": {
- "start": "string",
- "stop": "string"
}, - "capacity": 0,
- "fleet": [ ],
- "rules": [ ],
- "timeslotRule": [ ],
- "weekDay": 0,
- "found": true,
- "configuration": "string",
- "start": 0,
- "stop": 0,
- "platform": "string",
- "hub": "string",
- "usedCapacity": 0,
- "usedServiceTime": 0,
- "usedDimensions": { },
- "constraints": {
- "capacity": true,
- "serviceTime": 0,
- "dimensions": { },
- "rules": [ ]
}, - "startsAfterCutoffTime": true
}
], - "eta": {
- "margin": 0,
- "rounding": 0,
- "aheadOfSchedule": true,
- "inTimeWindow": true
}
}Get task information that changes frequently
Get information about a task's progress that are expected to change frequently.
Authorizations:
path Parameters
| trackingId required | string Tracking identifier of the task |
Responses
Response Schema: application/json
| driverLocation | Array of arrays Respectively last know longitude and lattitude. |
| precedingTasks | number |
| eta | string <date-time> The estimated date and time of arrival for this task, if the round has no delays. |
Response samples
- 200
{- "driverLocation": [
- 2.2945,
- 48.8584
], - "precedingTasks": 0,
- "eta": "1029-03-30T12:23:34.456Z"
}In Urbantz, a User is someone who can log-in to a given platform. The user has a role, and each role has a set of permissions.
For example, depending on the permissions, some users could not connect to the web interface, but could use the phone application.
Retrieve all users
Authorizations:
query Parameters
| excludeUsersFromOtherPlatforms | boolean If true, it returns only the users that belongs to this platform. |
| includeAnonymizedUsers | boolean If true, the anonymized users will be included in the response. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
[- {
- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}
]Create a new user
When calling this endpoint, you will create a new user linked to the platform (or sender) you are representing (which is determined by checking your credentials).
Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.
Authorizations:
Request Body schema: application/json
| email required | string The email address of the user. Needs to be unique globally in Urbantz |
| lastName required | string |
| firstName required | string |
| externalId required | string Your external identifier for this user. This must be unique for the whole platform. |
| password | string The password needs to be at least 8 characters long, and include an upper and a lower case letter, and a number. If a custom password policy is enabled, the configured requirements will apply. |
| hubExternalId | string the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information. |
| role required | string Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Coordinator" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager" The platform role identifier, as a string |
| sender | string the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Request samples
- Payload
{- "lastName": "Dupont",
- "firstName": "Jean",
- "externalId": "jean_dupont",
- "password": "Urbantz1",
- "hubExternalId": "hub_1_kuopio",
- "role": "Platform Cashier",
- "sender": "my-sender-name"
}Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Retrieve a specific user (id)
Retrieves a user, based on its internal identifier. The returned user is a basic version of the information we have.
Authorizations:
path Parameters
| id required | string (ID) Example: 507f191e810c19729de860ea The user identifier |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Update a specific user (id)
Update the information of a user, based on its internal identifier.
Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.
Authorizations:
path Parameters
| id required | string (ID) Example: 507f191e810c19729de860ea The user identifier |
Request Body schema: application/json
| firstName | string The new First name of the user |
| lastName | string The new Last name of the user |
| role | string Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Coordinator" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager" The new role name of the user |
| hubExternalId | string the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information. |
| sender | string the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Request samples
- Payload
{- "firstName": "Jacques",
- "lastName": "Brel",
- "role": "Platform Manager",
- "hubExternalId": "hub_1_helsinki",
- "sender": "my-sender-name"
}Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Ban a specific user (id)
Set a user as BANNED, based on its internal identifier. Banned users cannot log-in anymore to the services of Urbantz.
If you wish to re-enable a user, you can use the validate user (id) endpoint.
Authorizations:
path Parameters
| id required | string (ID) Example: 507f191e810c19729de860ea The user identifier |
query Parameters
| anonymize | boolean The personal data of the user registered in your platform will be anonymized. All data that are anonymized cannot be recovered from Urbantz anymore. This action is definitive. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Validate a specific user (id)
Set a user as VALIDATED, based on its internal identifier. Validated users are able to log-in to the services of Urbantz.
If you wish to block a user from using the Urbantz services, you can use the ban user (id) endpoint.
Authorizations:
path Parameters
| id required | string (ID) Example: 507f191e810c19729de860ea The user identifier |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Retrieve a specific user (email)
Retrieves a user, based on its email address. The returned user is a basic version of the information we have.
Authorizations:
path Parameters
| email required |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Update a specific user (email)
Update the information of a user, based on its email address.
Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.
Authorizations:
path Parameters
| email required |
Request Body schema: application/json
| firstName | string The new First name of the user |
| lastName | string The new Last name of the user |
| role | string Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Coordinator" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager" The new role name of the user |
| hubExternalId | string the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information. |
| sender | string the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Request samples
- Payload
{- "firstName": "Jacques",
- "lastName": "Brel",
- "role": "Platform Manager",
- "hubExternalId": "hub_1_helsinki",
- "sender": "my-sender-name"
}Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Ban a specific user (email)
Set a user as BANNED, based on its email address. Banned users cannot log-in anymore to the services of Urbantz.
If you wish to re-enable a user, you can use the validate user (email) endpoint.
Authorizations:
path Parameters
| email required |
query Parameters
| anonymize | boolean The personal data of the user registered in your platform will be anonymized. All data that are anonymized cannot be recovered from Urbantz anymore. This action is definitive. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Validate a specific user (email)
Set a user as VALIDATED, based on its email address. Validated users are able to log-in to the services of Urbantz.
If you wish to block a user from using the Urbantz services, you can use the ban user (email) endpoint.
Authorizations:
path Parameters
| email required |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Retrieve a specific user (ExternalId)
Retrieves a user, based on its External Identifier. The returned user is a basic version of the information we have.
Authorizations:
path Parameters
| ref required | string Example: contoso.jean_dupont.1 The user external identifier |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Update a specific user (ExternalId)
Update the information of a user, based on its External Identifier.
Please note, based on the role you assign to the user, some payload elements may become either required or forbidden to be sent. Please refer to the answer of the APIs if you have an issue, as it will tell you what is missing for the request to be accepted.
Authorizations:
path Parameters
| ref required | string Example: contoso.jean_dupont.1 The user external identifier |
Request Body schema: application/json
| firstName | string The new First name of the user |
| lastName | string The new Last name of the user |
| role | string Enum: "Cashier App & Web" "Customer Support" "Customer Support Manager" "Overwatch" "Platform All In One (MDD)" "Platform Coordinator" "Platform Dispatcher" "Platform Dispatcher Admin" "Platform Dispatcher Manager" "Platform Dispatcher Manager - Task Update" "Platform Driver" "Platform Manager" "Sender Agent - Tasks" "Sender Ticket Agent" "Sender Ticket Manager" "Store Dispatcher - CRUD" "Store Manager" The new role name of the user |
| hubExternalId | string the Hub identifier, defined by the platform. Required if using the role 'Cashier App & Web', or any other role with the requirement of a hub. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). You can also contact Urbantz to get this information. |
| sender | string the sender owning the user. This value is optional, depending on the role you try to assign. You can find out which fields are required for a role when trying to create a role using the interface, fields required are marked with an asterisk (*). Expected value from that field is the snake-case you can see in your browser URL when checking a given sender. See example. You can also contact Urbantz to get this information. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Request samples
- Payload
{- "firstName": "Jacques",
- "lastName": "Brel",
- "role": "Platform Manager",
- "hubExternalId": "hub_1_helsinki",
- "sender": "my-sender-name"
}Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Ban a specific user (ExternalId)
Set a user as BANNED, based on its External Identifier. Banned users cannot log-in anymore to the services of Urbantz.
If you wish to re-enable a user, you can use the validate user (ExternalId) endpoint.
Authorizations:
path Parameters
| ref required | string Example: contoso.jean_dupont.1 The user external identifier |
query Parameters
| anonymize | boolean The personal data of the user registered in your platform will be anonymized. All data that are anonymized cannot be recovered from Urbantz anymore. This action is definitive. |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Validate a specific user (ExternalId)
Set a user as VALIDATED, based on its External Identifier. Validated users are able to log-in to the services of Urbantz.
If you wish to block a user from using the Urbantz services, you can use the ban user (ExternalId) endpoint.
Authorizations:
path Parameters
| ref required | string Example: contoso.jean_dupont.1 The user external identifier |
Responses
Response Schema: application/json
| id | string (ID) |
| hubExternalId | string the Hub identifier, defined by the platform. |
string The email address of the user. Needs to be unique globally in Urbantz | |
| firstName | string The First Name of the user, as a string |
| lastName | string The Last Name of the user, as a string |
| status | string Enum: "VALIDATED" "DENIED" "BANNED" "INCOMPLETE" "CREATED" The status of this user |
| phoneNumber | string Phone number of the user |
| updated | string <date-time> Last time the user was updated. The value returned is an ISO 8601 date time string |
| when | string <date-time> Date and time when the user was created. The value returned is an ISO 8601 date time string |
| external | boolean Indicates if the user is external |
| role | string The role of the user, as seen in the dashboard |
| externalId | string the unique identifier for this user, for your platform |
Response samples
- 200
{- "id": "507f191e810c19729de860ea",
- "hubExternalId": "hub_1_kuopio",
- "firstName": "John",
- "lastName": "Doe",
- "status": "VALIDATED",
- "phoneNumber": "+1-202-555-0192",
- "updated": "2019-03-13T12:34:56.012Z",
- "when": "2019-03-13T12:34:56.012Z",
- "external": false,
- "role": "Platform Manager",
- "externalId": "jon_doe_hub1"
}Retrieve users' timesheets
Retrieves a list of all users with an existing timesheet, in addition of the basic information of each user.
Authorizations:
query Parameters
| dateFrom | string <date-time> A date used to filter from in the format YYYY-MM-DD |
| dateTo | string <date-time> a date used to filter to in the format YYYY-MM-DD |
Responses
Response Schema: application/json
| _id | string (ID) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
string The email address of the user. Needs to be unique globally in Urbantz | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| firstName | string The First Name of the user, as a string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lastName | string The Last Name of the user, as a string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| externalId | string the unique identifier for this user, for your platform | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Response samples
- 200
[- {
- "_id": "507f191e810c19729de860ea",
- "firstName": "John",
- "lastName": "Doe",
- "externalId": "jon_doe_hub1",
- "timesheet": {
- "days": [
- {
- "start": {
- "position": {
- "latitude": 0,
- "longitude": 0
}, - "timestamp": "string"
}, - "stop": {
- "position": {
- "latitude": 0,
- "longitude": 0
}, - "timestamp": "string"
}
}
], - "breaks": [
- {
- "start": {
- "position": {
- "latitude": 0,
- "longitude": 0
}, - "timestamp": "string"
}, - "stop": {
- "position": {
- "latitude": 0,
- "longitude": 0
}, - "timestamp": "string"
}
}
]
}
}
]Vehicles are the mean of transport for your missions. A vehicle is part of a fleet, eventually.
Vehicles are used to calculate the cost, speed and efficiency of a delivery - we base ourselves on the various criteria of a Vehicle object to determine the best paths for your deliveries, pickups, and services.
Retrieve all vehicles
Retrieves a list of all the vehicles that have been defined in the current platform.
Information includes reloading, if breaks are allowed for the vehicle, dimensions allowed inside, the cost per kilometer, etc.
Authorizations:
Responses
Response Schema: application/json
| _id | string (ID) | ||||
object | |||||
| |||||
| custom | boolean Default: false If this vehicle type is customized | ||||
| breaks | boolean If breaks are allowed for the driver of this vehicle | ||||
| platform | string (ID) | ||||
| name | string The name of the vehicle type | ||||
| maxOrders | number The number of orders the vehicle type can hold per travel | ||||
| orderByHour | number The number of orders the vehicle can do every hour | ||||
| maxDuration | number The maximum duration of a trip for this vehicle, in minutes | ||||
| maxDistance | number The maximum distance of a trip for this vehicle, in kilometers | ||||
| accelerationTime | number The acceleration time of the vehicle. Used for optimization | ||||
| fixedCost | number The fixed cost of the vehicle to do a round, per day. Used for optimization | ||||
| costPerUnitTime | number The cost of the vehicle per hour. Used for optimization | ||||
| costPerUnitDistance | number The cost of the vehicle per kilometer. Used for optimization | ||||
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. | |||||
| |||||
| __v | number This field is used for internal purposes only and should not be consumed. | ||||
| labels | Array of strings the labels assigned to the vehicle | ||||
| type | string Enum: "car" "bike" "scooter" "small_truck" "truck" "foot" the vehicle type, if any. Used for finding better paths for deliveries, where some kind of vehicles shall not be allowed. | ||||
Response samples
- 200
[- {
- "_id": "507f191e810c19729de860ea",
- "reloading": {
- "enabled": false,
- "time": 1
}, - "custom": false,
- "breaks": false,
- "platform": "507f191e810c19729de860ea",
- "name": "Semi-truck MANN-CO",
- "maxOrders": 100,
- "orderByHour": 100,
- "maxDuration": 1440,
- "maxDistance": 1500,
- "accelerationTime": 2,
- "fixedCost": 1,
- "costPerUnitTime": 1,
- "costPerUnitDistance": 0,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "__v": 0,
- "labels": [
- "ecologic"
], - "type": "car"
}
]Retrieve a specific vehicle
Retrieves a vehicle, based on its internal identifier.
The content is the same as for the Retrieve all vehicles endpoint, except this is not an array but directly the Vehicle object.
Authorizations:
path Parameters
| id required | string (ID) Example: 507f191e810c19729de860ea The vehicle id |
Responses
Response Schema: application/json
| _id | string (ID) | ||||
object | |||||
| |||||
| custom | boolean Default: false If this vehicle type is customized | ||||
| breaks | boolean If breaks are allowed for the driver of this vehicle | ||||
| platform | string (ID) | ||||
| name | string The name of the vehicle type | ||||
| maxOrders | number The number of orders the vehicle type can hold per travel | ||||
| orderByHour | number The number of orders the vehicle can do every hour | ||||
| maxDuration | number The maximum duration of a trip for this vehicle, in minutes | ||||
| maxDistance | number The maximum distance of a trip for this vehicle, in kilometers | ||||
| accelerationTime | number The acceleration time of the vehicle. Used for optimization | ||||
| fixedCost | number The fixed cost of the vehicle to do a round, per day. Used for optimization | ||||
| costPerUnitTime | number The cost of the vehicle per hour. Used for optimization | ||||
| costPerUnitDistance | number The cost of the vehicle per kilometer. Used for optimization | ||||
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. | |||||
| |||||
| __v | number This field is used for internal purposes only and should not be consumed. | ||||
| labels | Array of strings the labels assigned to the vehicle | ||||
| type | string Enum: "car" "bike" "scooter" "small_truck" "truck" "foot" the vehicle type, if any. Used for finding better paths for deliveries, where some kind of vehicles shall not be allowed. | ||||
Response samples
- 200
{- "_id": "507f191e810c19729de860ea",
- "reloading": {
- "enabled": false,
- "time": 1
}, - "custom": false,
- "breaks": false,
- "platform": "507f191e810c19729de860ea",
- "name": "Semi-truck MANN-CO",
- "maxOrders": 100,
- "orderByHour": 100,
- "maxDuration": 1440,
- "maxDistance": 1500,
- "accelerationTime": 2,
- "fixedCost": 1,
- "costPerUnitTime": 1,
- "costPerUnitDistance": 0,
- "dimensions": {
- "weight": 200,
- "volume": 0.2
}, - "__v": 0,
- "labels": [
- "ecologic"
], - "type": "car"
}Voice endpoints provide information about VoIP calls made by drivers to recipients using the Urbantz app.
Get voice log
This endpoint is for getting a list of all VoIP calls that occured for a specific task.
Authorizations:
path Parameters
| taskId required | string (ID) Example: 507f191e810c19729de860ea The task id |
Responses
Response Schema: application/json
object The user who initiated the call. | |||||
| |||||
| timestamp | string <date-time> The timestamp of when the call was initiated. | ||||
| status | string Enum: "finished" "failed" "ongoing" Whether the call failed, is still ongoing, or finished successfully. | ||||
| duration | integer >= 0 How many seconds the call was connected for. Not present for failed or ongoing calls. | ||||
Response samples
- 200
[- {
- "user": {
- "firstName": "string",
- "lastName": "string"
}, - "timestamp": "2019-03-13T12:34:56.012Z",
- "status": "finished",
- "duration": 0
}
]A WebHook (in this category) is not a real endpoint on our APIs. This is just a reference point allowing you to see what is the payload your server will receive when the said WebHook event is fired.
For more information on how to use this section of the documentation, please read the How to use the WebHooks documentation category of the introduction.
This section is a collection of payloads we could send to your server. Those are not actual endpoints of our API. To get more information about what they are, and how to set them up in your platform, please visit our Help Center.
You can use this documentation to see the payload we send to your servers, as specified in the "Request body" part of the request. The type of WebHook is defined in the URI. For example, the event "Optimization complete" will be displayed as POST /OptimizationComplete in our API documentation.
Your server has to respond with a status code 200 (OK) to acknowledge the data has been received on your side. If any other code is sent, an error will be triggered and an email can be sent to an email address you specified in the WebHook setup.
OptimizationComplete
The OptimizationComplete event is triggered whenever an optimization is finished successfully. This WebHook event can be found in the WebHooks section of a Flow.
It will send you an array of Task basic details, including the round name and its ID, and the sequence of the task in the round. This is interesting for your programs if you have logic depending on the result of an optimization.
Request Body schema: application/json
| date | string <date-time> The date of the task |
| driver | string The driver internal identifier. To get more details on the user, you can use the Retrieve a specific user (id) endpoint. |
| eta | string <date-time> The estimated date and time of arrival for this task, if the round has no delays. |
| id | string The internal identifier of the task |
| latitude | number [ -90 .. 90 ] The latitude of the pickup or delivery address |
| longitude | number [ -180 .. 180 ] The longitude of the pickup or delivery address |
| round | string The round ID, useful to get more information using for example the Retrieve a specific round endpoint. |
| roundName | string The round's name in which the task is assigned |
| sequence | integer The sequence number of this task, for the round it is assigned to |
| status | string (TaskStatus) Enum: "ARRIVED" "DELIVERED" "DEPARTED" "MISSING" "NOT_DELIVERED" "NOT_PICKED_UP" "PARTIAL_ARRIVED" "PARTIAL_DELIVERED" "PARTIAL_PICKED_UP" "PARTIAL_PREPARED" "PARTIAL_READY_TO_COLLECT" "PARTIAL_RECEIVED" "PENDING" "PICKED_UP" "PREPARED" "READY_TO_COLLECT" "RECEIVED" "RETURNED" "TRANSFERED" Provides more granular details about what's happening with the physical task. It is usually calculated based on the status of the items and it can change within a given progress stage |
| taskId | string The task-id of this task |
| updated | string <date-time> The date of when the task was edited for the last time |
Responses
Request samples
- Payload
[- {
- "date": "1029-03-30T12:23:34.456Z",
- "driver": "507f191e810c19729de860ea",
- "eta": "1029-03-30T12:23:34.456Z",
- "id": "507f191e810c19729de860ea",
- "latitude": 50.824853,
- "longitude": 4.365968,
- "round": "507f191e810c19729de860ea",
- "roundName": "R01",
- "sequence": 1,
- "status": "ARRIVED",
- "taskId": "169c9141eec",
- "updated": "2019-03-30T12:23:34.123Z"
}
]TaskChanged
The TaskChanged event is triggered whenever a task is modified. This WebHook event can be found in the WebHooks section of a Flow.
When that event occurs, the system will send you the task that was edited, taking into account the modifications that were applied by the editing. This event can be sent at the same time as TaskStatusChanged if the editing is a status transition.
Note: To avoid sending a large number of webhooks simultaneously this webhook will not be sent when using the global optimizer (from the announcements page). Please use OptimizationComplete instead.
Request Body schema: application/json
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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
[- {
- "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": "first",
- "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"
}
]TaskStatusChanged
The TaskStatusChanged event is triggered whenever a task has its status transiting from one to another. This WebHook event can be found in the WebHooks section of a Flow.
When that event occurs, the system will send you the task that got the status changed. This event can be sent at the same time as TaskChanged as a status transition requires to modify the task.
Note: To avoid sending a large number of webhooks simultaneously this webhook will not be sent when using the global optimizer (from the announcements page). Please use OptimizationComplete instead.
Request Body schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __v | number 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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timestamp | string <date-time> The date when the webhook was sent to your server | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "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": "first",
- "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",
- "timestamp": "2019-04-01T08:31:05.121Z"
}TasksAnnounced
The TasksAnnounced event is triggered when a new announcement is sent to Urbantz, either from a file upload, FTP upload, web, or API call. This WebHook can be found in the WebHooks tab of a Flow.
The system will return an array containing a detailed list of Tasks that were included in that announcement. If the announcement has been made in the web or via file upload, the createdBy key of each task will contain the basic information of the user at the origin of that announce.
Request Body schema: application/json
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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
[- {
- "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": "first",
- "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"
}
]TaskAssociated
The TaskAssociated event is triggered whenever a task has been associated to your platform. This webhook event can be configured in the Webhooks section of the Associates screen.
Request Body schema: application/json
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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timestamp | string <date-time> The date when the webhook was sent to your server | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
[- {
- "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": "first",
- "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",
- "timestamp": "2019-04-01T08:31:05.121Z"
}
]TaskUnassociated
The TaskUnassociated event is triggered whenever another platform has unassociated a task from your platform. This webhook event can be configured in the Webhooks section of the Associates screen.
Request Body schema: application/json
object (UserSummaryExternal) The user object. Present when the task was manually created by a user, null otherwise | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| __v | number 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" When provided, the task will be placed at the position requested in the round. The values accepted are “first” and “last”. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| timestamp | string <date-time> The date when the webhook was sent to your server | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "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": "first",
- "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",
- "timestamp": "2019-04-01T08:31:05.121Z"
}AnnouncementComplete
The AnnouncementComplete event is triggered whenever an announcement is completed, whether it succeeded or failed. This WebHook is available on the WebHooks tab of a Flow.
If the status is FAILED, the error object will be populated with a message and details of the error(s).
Request Body schema: application/json
| timestamp | string <date-time> The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp. | ||||||||||
| id required | string The internal ID of the announcement | ||||||||||
| status required | string Enum: "FAILED" "SUCCESS" The announcement's status | ||||||||||
| start required | string <date-time> The timestamp of when the announcement was started | ||||||||||
| end required | string <date-time> The timestamp of when the announcement was completed | ||||||||||
| mode required | string Enum: "API" "FILE" The way the announcement was provided | ||||||||||
object (AnnouncementErrors) The error information if the announcement's status is FAILED | |||||||||||
| |||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-13T12:34:56.012Z",
- "id": "string",
- "status": "FAILED",
- "start": "2019-03-13T12:34:56.012Z",
- "end": "2019-03-13T12:34:56.012Z",
- "mode": "API",
- "error": {
- "message": "string",
- "details": [
- {
- "message": "Unable to find column separator (expected \";\")",
- "line": "my_announcement.csv, line 123"
}
]
}
}AnnouncementCancelled
The AnnouncementCancelled event is triggered whenever someone deletes an announcement in the announcements tab of the web interface. This WebHook can be found in the WebHooks tab of a Flow.
When getting this WebHook, we send the bare minimum information about the tasks that were in the announcement, which means you'll get the internal identifier and the TaskId of each task affected by this announcement deletion. You can then use the Retrieve a specific task to get detailed information about the tasks.
Request Body schema: application/json
| announcement | string (AnnouncementID) The identifier of the announcement | ||||
Array of objects (TaskMinimalIdentifiers) | |||||
Array
| |||||
| timestamp | string <date-time> The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp. | ||||
Responses
Request samples
- Payload
{- "announcement": "507f191e810c19729de860ea",
- "tasks": [
- {
- "_id": "507f191e810c19729de860ea",
- "taskId": "evening PACK 123142-CAZD"
}
], - "timestamp": "2019-03-13T12:34:56.012Z"
}TicketCreated
The TicketCreated event is triggered whenever a ticket is created in your platform. This WebHook can be found in the WebHooks tab of the General platform settings.
If you want to obtain more information about the related task or round, you are invited to use our Retrieve a specific task and Retrieve a specific round endpoint.
Request Body schema: application/json
| labels | Array of strings (TicketLabels) | ||||||||||||||||||||||||||||||
| status | string (TicketStatus) Enum: "OPEN" "TREATED" "CLOSED" The status of the ticket | ||||||||||||||||||||||||||||||
| when | string <date-time> creation date of the ticket | ||||||||||||||||||||||||||||||
Array of objects (TicketLog) An array of log objects for that ticket | |||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||
Array of objects (TicketComment) a list of comments for the given ticket | |||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||
| _id | string (ID) | ||||||||||||||||||||||||||||||
| class | string Enum: "task" "round" The kind of ticket. A task ticket will have additional properties related to the task, and a round ticket will have additional properties related to the round. | ||||||||||||||||||||||||||||||
object (TicketTask) A task relation object. Provides the database ID as well as the TaskID. Only available if the class is 'task'. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| round | string The round database ID for this ticket | ||||||||||||||||||||||||||||||
| taskId | string (TaskId) Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier. | ||||||||||||||||||||||||||||||
| platform | string (ID) | ||||||||||||||||||||||||||||||
| associated | string (ID) | ||||||||||||||||||||||||||||||
| associatedName | string The platform name to which the ticket is associated to. Used when tickets, rounds or tasks are going from a platform to another for example. | ||||||||||||||||||||||||||||||
| by | string (ID) | ||||||||||||||||||||||||||||||
| priority | number Enum: 1 2 3 The priority of the ticket. 1 is for low, 2 for medium, 3 for high. | ||||||||||||||||||||||||||||||
| type | string A string that defines the kind of ticket, as defined in the Ticket settings. Please note that only the types defined in the Ticket settings are allowed as a value. | ||||||||||||||||||||||||||||||
| title | string Title of this ticket | ||||||||||||||||||||||||||||||
object (TicketCategory) Contains the information about the category the ticket has been set to. If no category is defined, it will be null. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
object (UserRelation) | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
object (UserRelation) | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| description | string The description of the ticket | ||||||||||||||||||||||||||||||
| userName | string The full name of the creator of this ticket, as a string | ||||||||||||||||||||||||||||||
| assignedToName | string The full name of the user assigned to this ticket, as a string | ||||||||||||||||||||||||||||||
| id | string (ID) | ||||||||||||||||||||||||||||||
| timestamp | string <date-time> The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp. | ||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "labels": [
- "frozen"
], - "status": "OPEN",
- "when": "2019-03-13T12:34:56.012Z",
- "log": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "_id": "507f191e810c19729de860ea",
- "by": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "assignedTo": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "to": "OPEN"
}
], - "comments": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "_id": "507f191e810c19729de860ea",
- "user": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "comment": "string"
}
], - "_id": "507f191e810c19729de860ea",
- "class": "task",
- "task": {
- "id": "507f191e810c19729de860ea",
- "taskId": "my-task-id"
}, - "round": "string",
- "taskId": "my-task-id",
- "platform": "507f191e810c19729de860ea",
- "associated": "507f191e810c19729de860ea",
- "associatedName": "Another delivery in the truck",
- "by": "507f191e810c19729de860ea",
- "priority": 1,
- "type": "string",
- "title": "string",
- "category": {
- "parent": "507f191e810c19729de860ea",
- "parentName": "string",
- "_id": "507f191e810c19729de860ea",
- "path": "5b7acfd24e746602c957dab9.5b7acff54e746602c957dabf",
- "name": "string"
}, - "assignedTo": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "user": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "description": "string",
- "userName": "string",
- "assignedToName": "string",
- "id": "507f191e810c19729de860ea",
- "timestamp": "2019-03-13T12:34:56.012Z"
}TicketUpdated
The TicketUpdated event is triggered whenever a ticket is edited in your platform. This WebHook can be found in the WebHooks tab of the General platform settings.
The reason of the edit could be a manual change of some properties (change the priority, add a comment, ...) or an action taken on the ticket (Mark as treated, assign ticket to someone or self, ...).
If you want to obtain more information about the related task or round, you are invited to use our Retrieve a specific task and Retrieve a specific round endpoint.
Request Body schema: application/json
| labels | Array of strings (TicketLabels) | ||||||||||||||||||||||||||||||
| status | string (TicketStatus) Enum: "OPEN" "TREATED" "CLOSED" The status of the ticket | ||||||||||||||||||||||||||||||
| when | string <date-time> creation date of the ticket | ||||||||||||||||||||||||||||||
Array of objects (TicketLog) An array of log objects for that ticket | |||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||
Array of objects (TicketComment) a list of comments for the given ticket | |||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||
| _id | string (ID) | ||||||||||||||||||||||||||||||
| class | string Enum: "task" "round" The kind of ticket. A task ticket will have additional properties related to the task, and a round ticket will have additional properties related to the round. | ||||||||||||||||||||||||||||||
object (TicketTask) A task relation object. Provides the database ID as well as the TaskID. Only available if the class is 'task'. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| round | string The round database ID for this ticket | ||||||||||||||||||||||||||||||
| taskId | string (TaskId) Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier. | ||||||||||||||||||||||||||||||
| platform | string (ID) | ||||||||||||||||||||||||||||||
| associated | string (ID) | ||||||||||||||||||||||||||||||
| associatedName | string The platform name to which the ticket is associated to. Used when tickets, rounds or tasks are going from a platform to another for example. | ||||||||||||||||||||||||||||||
| by | string (ID) | ||||||||||||||||||||||||||||||
| priority | number Enum: 1 2 3 The priority of the ticket. 1 is for low, 2 for medium, 3 for high. | ||||||||||||||||||||||||||||||
| type | string A string that defines the kind of ticket, as defined in the Ticket settings. Please note that only the types defined in the Ticket settings are allowed as a value. | ||||||||||||||||||||||||||||||
| title | string Title of this ticket | ||||||||||||||||||||||||||||||
object (TicketCategory) Contains the information about the category the ticket has been set to. If no category is defined, it will be null. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
object (UserRelation) | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
object (UserRelation) | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| description | string The description of the ticket | ||||||||||||||||||||||||||||||
| userName | string The full name of the creator of this ticket, as a string | ||||||||||||||||||||||||||||||
| assignedToName | string The full name of the user assigned to this ticket, as a string | ||||||||||||||||||||||||||||||
| id | string (ID) | ||||||||||||||||||||||||||||||
| timestamp | string <date-time> The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp. | ||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "labels": [
- "frozen"
], - "status": "OPEN",
- "when": "2019-03-13T12:34:56.012Z",
- "log": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "_id": "507f191e810c19729de860ea",
- "by": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "assignedTo": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "to": "OPEN"
}
], - "comments": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "_id": "507f191e810c19729de860ea",
- "user": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "comment": "string"
}
], - "_id": "507f191e810c19729de860ea",
- "class": "task",
- "task": {
- "id": "507f191e810c19729de860ea",
- "taskId": "my-task-id"
}, - "round": "string",
- "taskId": "my-task-id",
- "platform": "507f191e810c19729de860ea",
- "associated": "507f191e810c19729de860ea",
- "associatedName": "Another delivery in the truck",
- "by": "507f191e810c19729de860ea",
- "priority": 1,
- "type": "string",
- "title": "string",
- "category": {
- "parent": "507f191e810c19729de860ea",
- "parentName": "string",
- "_id": "507f191e810c19729de860ea",
- "path": "5b7acfd24e746602c957dab9.5b7acff54e746602c957dabf",
- "name": "string"
}, - "assignedTo": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "user": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "description": "string",
- "userName": "string",
- "assignedToName": "string",
- "id": "507f191e810c19729de860ea",
- "timestamp": "2019-03-13T12:34:56.012Z"
}TicketClosed
The TicketClosed event is triggered whenever a ticket is closed in your platform. This WebHook can be found in the WebHooks tab of the General platform settings.
A ticket that has been closed can no longer be modified.
If you want to obtain more information about the related task or round, you are invited to use our Retrieve a specific task and Retrieve a specific round endpoint.
Request Body schema: application/json
| labels | Array of strings (TicketLabels) | ||||||||||||||||||||||||||||||
| status | string (TicketStatus) Enum: "OPEN" "TREATED" "CLOSED" The status of the ticket | ||||||||||||||||||||||||||||||
| when | string <date-time> creation date of the ticket | ||||||||||||||||||||||||||||||
Array of objects (TicketLog) An array of log objects for that ticket | |||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||
Array of objects (TicketComment) a list of comments for the given ticket | |||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||
| _id | string (ID) | ||||||||||||||||||||||||||||||
| class | string Enum: "task" "round" The kind of ticket. A task ticket will have additional properties related to the task, and a round ticket will have additional properties related to the round. | ||||||||||||||||||||||||||||||
object (TicketTask) A task relation object. Provides the database ID as well as the TaskID. Only available if the class is 'task'. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| round | string The round database ID for this ticket | ||||||||||||||||||||||||||||||
| taskId | string (TaskId) Your own task identifier. This enables you to use your backend (ERP, CMS, ...) system identifier. | ||||||||||||||||||||||||||||||
| platform | string (ID) | ||||||||||||||||||||||||||||||
| associated | string (ID) | ||||||||||||||||||||||||||||||
| associatedName | string The platform name to which the ticket is associated to. Used when tickets, rounds or tasks are going from a platform to another for example. | ||||||||||||||||||||||||||||||
| by | string (ID) | ||||||||||||||||||||||||||||||
| priority | number Enum: 1 2 3 The priority of the ticket. 1 is for low, 2 for medium, 3 for high. | ||||||||||||||||||||||||||||||
| type | string A string that defines the kind of ticket, as defined in the Ticket settings. Please note that only the types defined in the Ticket settings are allowed as a value. | ||||||||||||||||||||||||||||||
| title | string Title of this ticket | ||||||||||||||||||||||||||||||
object (TicketCategory) Contains the information about the category the ticket has been set to. If no category is defined, it will be null. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
object (UserRelation) | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
object (UserRelation) | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
| description | string The description of the ticket | ||||||||||||||||||||||||||||||
| userName | string The full name of the creator of this ticket, as a string | ||||||||||||||||||||||||||||||
| assignedToName | string The full name of the user assigned to this ticket, as a string | ||||||||||||||||||||||||||||||
| id | string (ID) | ||||||||||||||||||||||||||||||
| timestamp | string <date-time> The date the action occurred. For instance, if you receive a ticketClosed event, it means the ticket was closed at this timestamp. | ||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "labels": [
- "frozen"
], - "status": "OPEN",
- "when": "2019-03-13T12:34:56.012Z",
- "log": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "_id": "507f191e810c19729de860ea",
- "by": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "assignedTo": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "to": "OPEN"
}
], - "comments": [
- {
- "when": "2019-03-13T12:34:56.012Z",
- "_id": "507f191e810c19729de860ea",
- "user": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "comment": "string"
}
], - "_id": "507f191e810c19729de860ea",
- "class": "task",
- "task": {
- "id": "507f191e810c19729de860ea",
- "taskId": "my-task-id"
}, - "round": "string",
- "taskId": "my-task-id",
- "platform": "507f191e810c19729de860ea",
- "associated": "507f191e810c19729de860ea",
- "associatedName": "Another delivery in the truck",
- "by": "507f191e810c19729de860ea",
- "priority": 1,
- "type": "string",
- "title": "string",
- "category": {
- "parent": "507f191e810c19729de860ea",
- "parentName": "string",
- "_id": "507f191e810c19729de860ea",
- "path": "5b7acfd24e746602c957dab9.5b7acff54e746602c957dabf",
- "name": "string"
}, - "assignedTo": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "user": {
- "_id": "507f191e810c19729de860ea",
- "id": "507f191e810c19729de860ea",
- "firstName": "string",
- "lastName": "string"
}, - "description": "string",
- "userName": "string",
- "assignedToName": "string",
- "id": "507f191e810c19729de860ea",
- "timestamp": "2019-03-13T12:34:56.012Z"
}round.created
The round.created event is triggered whenever a new round has been created in your platform. This WebHook can be found under the WebHooks tab of the General platform settings.
If you wish to learn how to create a round, please visit the How to optimize/create rounds on our Help Center.
Request Body schema: application/json
| timestamp | string <date-time> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| eventType | string Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed" The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RoundWebhookBody) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "round.created",
- "eventType": "round.created",
- "round": {
- "_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"
}, - "vehicleData": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}
}round.validated
The round.validated event is triggered whenever a round is validated. A round can be validated if and only if the current status of the round is CREATED. The WebHook can be found in the WebHooks tab of the General platform settings.
Once the round is validated, it is now possible to publish it, making it available for the drivers.
Request Body schema: application/json
| timestamp | string <date-time> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| eventType | string Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed" The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RoundWebhookBody) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "round.created",
- "eventType": "round.created",
- "round": {
- "_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"
}, - "vehicleData": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}
}round.published
The round.published event is triggered whenever a round is published. A round can be published if and only if the current status of the round is VALIDATED. The WebHook can be found in the WebHooks tab of the General platform settings.
Once the round is published, drivers will be able to take it as a mission, and start preparing the round.
Request Body schema: application/json
| timestamp | string <date-time> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| eventType | string Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed" The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RoundWebhookBody) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "round.created",
- "eventType": "round.created",
- "round": {
- "_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"
}, - "vehicleData": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}
}round.in_preparation
The round.in_preparation event is triggered whenever a round is being prepared by a driver or dispatcher. A round can be prepared if and only if the current status of the round is published. The WebHook can be found in the WebHooks tab of the General platform settings.
Once the round is prepared, it becomes possible to start delivering it. the status for a round being in the process of delivery is called ongoing.
Request Body schema: application/json
| timestamp | string <date-time> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| eventType | string Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed" The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RoundWebhookBody) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "round.created",
- "eventType": "round.created",
- "round": {
- "_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"
}, - "vehicleData": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}
}round.ongoing
The round.ongoing event is triggered whenever a round is prepared by a driver or dispatcher, and the driver started driving to the first delivery point. The WebHook can be found in the WebHooks tab of the General platform settings.
Once the round is completed (all parcels have been either delivered, partially delivered or not delivered), the round will switch to the status completed.
Request Body schema: application/json
| timestamp | string <date-time> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| eventType | string Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed" The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RoundWebhookBody) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "round.created",
- "eventType": "round.created",
- "round": {
- "_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"
}, - "vehicleData": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}
}round.completed
The round.completed event is triggered whenever a round is finished being delivered by a driver. The parcels could either be delivered, partially delivered, or not delivered. In any case, the round is marked as completed as there is no more address to reach to deliver or pickup one or more parcels. The WebHook can be found in the WebHooks tab of the General platform settings.
Request Body schema: application/json
| timestamp | string <date-time> | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| eventType | string Enum: "round.created" "round.validated" "round.published" "round.in_preparation" "round.ongoing" "round.completed" The webhook event type which describes the new round status | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (RoundWebhookBody) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "round.created",
- "eventType": "round.created",
- "round": {
- "_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"
}, - "vehicleData": {
- "name": "string",
- "id": "507f191e810c19729de860ea",
- "_id": "507f191e810c19729de860ea"
}
}
}round.analytics (RDD)
The round.analytics event is triggered whenever a metric is available after a round is complete.
The payload will change based on the type. This is a description of the payload when the type is for the Real Distance Driven metric
Request Body schema: application/json
| timestamp | string <date-time> | ||||||
| type | string Value: "REAL_DISTANCE_DRIVEN" The type of analytics in the payload | ||||||
| eventType | string Value: "round.analytics" The webhook event type | ||||||
object (RealDistanceDriven) | |||||||
| |||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "REAL_DISTANCE_DRIVEN",
- "eventType": "round.analytics",
- "payload": {
- "realDistanceInMeter": 0,
- "confidenceLevel": "HIGH",
- "when": "2019-03-13T12:34:56.012Z"
}
}round.analytics (GHG)
The round.analytics event is triggered whenever a metric is available after a round is complete.
The payload will change based on the type. This is a description of the payload when the type is for the Green House Gases metric
Request Body schema: application/json
| timestamp | string <date-time> | ||||||||||||||||||||||||||||||
| type | string Value: "GHG_EMISSION" The type of analytics in the payload | ||||||||||||||||||||||||||||||
| eventType | string Value: "round.analytics" The webhook event type | ||||||||||||||||||||||||||||||
object (RoundGhg) | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
Responses
Request samples
- Payload
{- "timestamp": "2019-03-15T12:34:56.000Z",
- "type": "GHG_EMISSION",
- "eventType": "round.analytics",
- "payload": {
- "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"
}
]
}
}Zones are polygons representing delivery areas. The zones can be used in allocation rules, optimization problems, etc…
Retrieve zones
This endpoint fetches a paginated list of all the zones configured in your platform. It also allows to filter the list by specific criteria.
Authorizations:
query Parameters
| page | number (Page) Default: 0 The page index of the requested records |
| pageSize | number <= 500 Default: 100 The page size of the requested records |
| names | Array of strings <= 100 items The zone names to search for. It's a case sensitive exact match search. |
| latitude | number [ -90 .. 90 ] Example: latitude=50.824853 The latitude to search for |
| longitude | number [ -180 .. 180 ] Example: longitude=4.365968 The longitude to search for |
Responses
Response Schema: application/json
| id | string The identifier of the zone | ||||
| name | string The name of the zone | ||||
| hub | string The identifier of the hub | ||||
| color | string The color of the zone (hexadecimal color code) | ||||
Array of objects The list of vertices of the polygon | |||||
Array
| |||||
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": "65671355a478379082937c94",
- "name": "My Zone",
- "hub": "5ef9d0a6192d6c0bca0399b7",
- "color": "#ADFF2F",
- "geometry": [
- {
- "latitude": 50.824853,
- "longitude": 4.365968
}
]
}
]