Link Search Menu Expand Document

Welcome

Welcome to the TIER API Version 1.

This documentation provides the essentials to integrate with TIER’s Mobility API Version 1.

ℹ Access is limited for different endpoints and zones for each API key individually.

Format

The TIER API is using the JSON:API standard.

Versioning

The API is versioned using a prefix in the URL, e.g. /v2 for the second version. There are still some unversioned (deprecated) endpoints. If you are using these, please note that they will stop working in future releases of this API.

Always use the newest API version and contact your account manager if there is a reason why you cannot switch to a newer version.

Backwards-Compatible Minor Updates

We will only break backwards compatibility in new API versions, which have their own URL prefix. That means that all actions or resources will remain backwards compatible as long as your integration allows for the following changes to be made on our side:

  • An endpoint resource might return new fields, e.g. {"foo": "bar"} might be {"foo": "bar", "baz": 123} tomorrow
  • An endpoint might accept new optional data or parameters
  • An endpoint might ignore previously required data while providing same functionality

Terms & Conditions

Please find our current Terms & Conditions here:

View unbranded terms and conditions

Users have to accept these Terms & Conditions before using our services.

Privacy Policy

Please find our current Privacy Policy here:

View Privacy Policy

Users have to accept this Privacy Policy before using our services.

FAQs

Please find the Frequently Asked Questions (FAQs) for TIER Mobility

View Tier Mobility FAQ

Production and staging URLs

Please note that there are 2 different URLs for our staging and for our production environment.

Our production environment is accessible via https://platform.tier-services.io/v1.

ℹ Please note that we have currently disabled our staging environment. Your requests to https://platform.tier-staging.io/v1 will not get any responses as of now.

ℹ Note that production and staging environments do have different API keys.

Testing using a TIER vehicle

As our staging environment is currently not available, we ask you to use our production environment in order to execute tests. A test vehicle is made available, in order to access it, please call the vehicle ID and set the customerStartLocation as the name of the respective city (depends on test vehicle). Please note that in order to successfully create a rental, the vehicle state should be set as ACTIVE, if this is not the case please contact your point of contact at TIER in order to change it.

In order to not get charged for the rentals, we kindly ask you to:

  • Stick to only one test vehicle
  • Not run the rentals over 30 seconds

Test e-Scooter 1 :

  • Zone: TEST
  • Vehicle code: 210751
  • Vehicle ID: add546b9-86d2-4666-963a-7b33e7313d83

Test e-Scooter 2 :

  • Zone: TEST
  • Vehicle code: 130033
  • Vehicle ID: 2e58dd5b-7baa-4039-a289-c898f543d5c6

Test e-Moped :

  • Zone: TEST
  • Vehicle code: 512462
  • Vehicle ID: e8476e70-f3ff-45fe-a652-03df3c3d21c9

Test e-Bike :

  • Zone: TEST
  • Vehicle code: 600417
  • Vehicle ID: 74073fcd-d0f6-47e2-a331-152b18c0ff20

Authentication

You must replace TIER API KEY with your personal API key.

TIER is using an API Keys and JSON Web Token (JWT) based authentication, depending on the endpoint. To register for an API key please ask your TIER contact. Each API key is bound to certain permissions that determine which zones and endpoints you can access.

🚨 Do not include the API key in your Mobile or Web client, as they are very powerful! The API Key may only be used in secured backend services, hidden from your customers.

OAuth client credentials

MobilityAPI endpoints are using OAuth client credentials flow to authorize the requests which means an access token needs to be used in Authorization: Bearer <Token> header. The token can be requested on our token endpoint in exchange for client ID and secret. Please use HTTP Basic authentication to retrieve the access token from this endpoint with mobility-api:read or mobility-api:rides scope. Note an access token has an expiration time (2 hours), after expired it can not be used (the request will be rejected HTT 401). This case a new access token must be requested from the token endpoint. The response contains the expiration date as well for the token.

🔑 To obtain client id and client secret please ask your TIER contact. Every relevant access details will be shared. Example token request:

curl -L -X POST 'https://auth.tier-services.io/oauth2/aus41nfrunfKbXbOr417/v1/token'  \
    --header "Authorization: Basic $(base64 <(echo -n '<clientID>:<clientSecret>'))" \
    --data 'grant_type=client_credentials&scope=mobility-api:read'

Example token response:

// success HTTP 200:
{"token_type":"Bearer", "expires_in":3600, "access_token":<TOKEN>, "scope":"mobility-api:read"}
// error HTTP 400:
{"error":"server_error", "error_description":"Unauthorized"}

🚨 Client secret is a secret information you should never share it publicly in any form (e.g including it in a website source-code).

Encodings

TIER API supports deflate and gzip encoding formats, if you would like to recive encoded data in these format please indicate it in Accept-Encoding HTTP header. More information.

ℹ Try to avoid using Accept-Encoding: * instead specify the exact encoding type. If you use wildcard however, it will default to deflate, but it’s subject to change in the future.

Design-kit

In case you require our colors, logo, font, or scooter pictures please check out our design kit.

View TIER Design Kit

You can find additional design material on www.tier.app/press/.

TIER sets high emphasis on safety, both our riders and other traffic participants. We remind our users to be attentive and to stay aware of traffic and signals. Equally, since TIER is making space for all city inhabitants, we highlight following the local rules of parking, being respectful of others, and to not block anything.

  • Please educate your users on the client-side accordingly

User Flow

If you are looking for some more information on the UI/UX flow in the TIER app for our different vehicle types and use cases, please check out the folder below

TIER App User Flow

Integrations FAQ

In order to facilitate the integration process for you, we have set up a FAQ page, giving you answers to the most common questions we receive from our integration partners.

TIER Integrations FAQ