Urbantz API documentation (v2)

About our APIs

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

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

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

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

Authentication

Urbantz offers two authentication methods: Basic auth with API key and oAuth2 / OpenId Connect.

To authenticate with API key, you need to copy the api key shown in Administration > Platform > General and include it in every request as username in the authorization header or use the header “x-api-key”.

To authenticate with OpenID, you need to create a client in Administration > Platform > General > Security and use the following URL to retrieve the temporary token

https://auth.urbantz.com/realms/{account_snake}-{account_type}/protocol/openid-connect/token being:

1. account_snake the snake-case identifier used in the URL of your platform or sender portal.

2. account_type the type of account. It can be “platform“ or “sender”.

Request

curl --location --request POST 'https://auth.urbantz.com/realms/my_account_name-platform/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{ CLIENT_ID }}' \
--data-urlencode 'client_secret={{ CLIENT_SECRET }}' \
--data-urlencode 'grant_type=client_credentials'

Response

{
    "access_token": {{ JWT_TOKEN }},
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "urbantz"
}

In the response you will find the access token and the expiration time:

• access_token is the Bearer token that will be passed to the Urbantz API
• expires_in indicates how long (in seconds) the token is valid (5 minutes).

The access token must be provided in every request using the authorization header.

Example

curl --location --request GET '{{ URBANTZ_API }}/v2/announcement' \
--header 'Authorization: Bearer {ACCESS_TOKEN}';

Pagination

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

Introduction

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

How Pagination Works

When you make requests to endpoints that support pagination, the results are constrained to a specific page size. This page size is determined by the endpoint itself and the size of the retrieved data.

To utilize pagination, you are required to include the page number with every request. Although the page size is optional, you can find information about the default value and maximum limit for each endpoint in their respective documentation.

Parameters

• page: An integer indicating the page number to retrieve. The default value is 0.

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

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.

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.

Rate Limiting

To protect the platform, all API endpoints are subject to rate limiting. Limits are enforced both per user and per platform.

When a request is rejected due to rate limiting, the API responds with HTTP 429 Too Many Requests and the following headers:

Your integration should inspect the Retry-After header and back off accordingly before retrying.

You can use the GET /test-rate-limiter endpoint to verify that your client handles 429 responses correctly without triggering any side effects.

If you have more questions

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