Urbantz API documentation (v2)

Download OpenAPI specification:Download

Introduction

About our APIs

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

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

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

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

Where to test endpoints

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

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

Webhooks usage

The WebHooks 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.

If you have more questions

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

Authentication

BasicAuth

The preferred method of authentication is the BasicAuth mechanism, available in almost every browser and client. The advantage of this method is that you don't need to add any additional header.

The username is the platform key and the password is the flow key (also called private key), if required.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Platform key

The platform key is the key identifying the platform you are doing the call for.

It can either be added in the header, or as a username in BasicAuth.

Security Scheme Type API Key
Header parameter name: x-api-key

Flow key

The flow key is the key identifying the flow to be used for announcing new tasks.

If you use BasicAuth, the flow key has to be inserted as password.

Security Scheme Type API Key
Header parameter name: x-api-secret

Announcements

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

Retrieve announcements

Returns a list of announcements. By default, it will return the announcements for today (UTC). If you provide the date query parameter, it will return announcements for that specific date instead.

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

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

The announcement's status

Responses

200

A JSON array of announcements

get /announcement

Production

https://api.urbantz.com/v2/announcement

Sandbox

https://api.sandbox.urbantz.com/v2/announcement

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Attachments

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

Get attachment URI

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

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

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

Authorizations:
path Parameters
type
required
string
Example: tasks

The type of the entity (plural form)

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

302

A redirect to the location of the attachment, when one has been found

get /attachments/{type}/{id}/{key}

Production

https://api.urbantz.com/v2/attachments/{type}/{id}/{key}

Sandbox

https://api.sandbox.urbantz.com/v2/attachments/{type}/{id}/{key}

Optimizer

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

Optimize target flows

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:

  • hub
  • shift
  • flow
  • date

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

Responses

200

Successfully started optimization

get /optimizer/global

Production

https://api.urbantz.com/v2/optimizer/global

Sandbox

https://api.sandbox.urbantz.com/v2/optimizer/global

Rounds

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

Retrieve all rounds

Fetches a paginated list of all rounds on the authenticated platform. By default, the results displayed are date independant. 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
Default: 0

The page index of the requested records

pageSize
number
Default: 10

The page size of the requested records

hub
string <mongodb-id>
Example: hub=507f191e810c19729de860ea

The internal hub identifier (Urbantz)

Responses

200

A JSON array of rounds

get /round

Production

https://api.urbantz.com/v2/round

Sandbox

https://api.sandbox.urbantz.com/v2/round

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

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 <mongodb-id>
Example: 507f191e810c19729de860ea

The task identifier

Responses

200

A round

get /round/{id}

Production

https://api.urbantz.com/v2/round/{id}

Sandbox

https://api.sandbox.urbantz.com/v2/round/{id}

Response samples

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