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.

Some of our endpoints implement pagination, which allows you to retrieve a limited number of results per query and navigate through these results using pages.

Introduction

In this section, we'll explain how pagination works in Urbantz APIs. Pagination is employed in endpoints that return lists of entities such as tasks, rounds, reservations, or announcements. This approach enhances efficiency by managing large datasets effectively.

How Pagination Works

When you make requests to endpoints that support pagination, the results are constrained to a specific page size. This page size is determined by the endpoint itself and the size of the retrieved data. To utilize pagination, you are required to include the page number with every request. Although the page size is optional, you can find information about the default value and maximum limit for each endpoint in their respective documentation.

Parameters

• page: An integer indicating the page number to retrieve. The default value is 0.
• pageSize: An integer representing the number of results to retrieve in a single request. Each endpoint has a default value and a predefined maximum limit.

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.

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

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.