MotionTools API documentation (1.0.0)

Download OpenAPI specification:Download

License: commercial

Introduction

Welcome to the MotionTools API documentation! The MotionTools API is a REST API which allows you to programatically interact with MotionTools in order to build or enhance your delivery or fleet management business.

Our API has predictable resource-oriented URLs, accepts JSON-encoded and form-encoded requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

πŸ“˜ If you're not yet ready to integrate a specific API, more high-level feature and product documentation can be found on our help center.

⚑ Quickstart articles

In many cases the first points of integration is either creation of a booking in Motiontools from another system that you may already be using or reacting to events like a booking being completed by a driver via Webhooks.

Here are some related articles in our help center that can help you to quickly kick things off the ground πŸš€:

🌎 Base URL

The Base URL for the MotionTools API is https://api.motiontools.io/.

πŸ”Ž Features overview

The MotionTools API can be used to manage all aspects of your business that are managed by MotionTools.

To name a few:

Furthermore, Motiontools can provide real-time updates on everything that happens in your account through Webhooks.

Definitions

Using the MotionTools API requires a basic understanding of how bookings, customers, service areas and a few other relevant concepts are structured, and how they relate to one another.

You can find a corresponding overview in our MotionTools help center glossary.

πŸ€·β€β™‚οΈ Still not sure how to start?

Contact our customer support agents here and we’ll make sure to clarify all your questions.

Authentication

Here you can find more info on the authentication mechanisms used for the communication with MotionTools backend.

API Token Auth

API Tokens can be created by admin and customer accounts via the Web Dashboard, and carry full permissions to the API as the token's owning user.

API Tokens are intended to be used by other servers interacting with the MotionTools API, and they are not intended to be used by user-facing applications. Do not use API Tokens to authenticate client apps and do not embed API Tokens in client side code, as they can easily be extracted. If you need to authenticate user-facing applications (e.g. Android/iOS apps, or other web dashboards), please authenticate using Access tokens.

Other relevant points when it comes to authenticating with API tokens:

  • the X-Client-Version (see here) header must be ommited;
  • API Tokens never expire. A token can be manually deleted from the Web Dashboard however.

Access Token Auth

Access token authentication is typical for client applications like mobile apps.

πŸ’‘ In a typical MotionTools integration you won't be dealing with access token authentication. Prefer API tokens instead.

A valid access token can be obtained via the sign up, sign in and refresh token endpoints and always expires after a predefined amount of time. Once expired, it needs to be refreshed via the refresh token endpoint. By either signing out a user, or by blocking a user’s account, the access token (and the associated refresh token) will be invalidated.

Client Identification

πŸ’‘ In a typical MotionTools integration you won't be dealing with client identifiers. When using API tokens you must not send the X-Client-Version header used for client identification at all.

All clients must set the X-Client-Version header to their applicable Client ID and Version, like MyCustomerApp/1.0.0. The header is used for identifying the applicable tenant to enable multi-tenancy, as well as for enabling the expiration of outdated clients.

  • If the client version is disallowed the backend will send a 410 Gone HTTP response code. Upon this response clients must show a notification to the user to upgrade their app.
  • If the client version is unknown the backend will return a 400 HTTP response with the unknown_tenant error code.
  • Some client versions are permitted only for a specific user role. This is currently only enforced on sign up and sign in routes, which will render the user unable to obtain an access/refresh token. If the client is being used by a user that doesn't have a supported role, a 403 HTTP response code will be returned with the error_code client_role_mismatch. It's up to the client to handle this specific status and error code combination gracefully.

Deprecations

A X-Deprecated response header is returned only on staging if a deprecated endpoint is called, or if a deprecated parameter is passed. When a deprecated endpoint is called, this header will have deprecated_action as value. If a deprecated parameter is passed, then the name of this parameter will be the value.

Errors

Errors are broadly indicated via HTTP status and further narrowed down using an error code in the response payload. Human-readable descriptions are implementor-facing and meant to help in understanding issues, not user-facing.

{
  "error_code": "hello_world",
  "description": "Some brief description"
}

Some errors like failed validations may contain additional data in the response in order to clarify to the user what was wrong more easily. These messages are localized based on the sent Accept-Language and should be displayed as applicable:

  • If an error key matches a request parameter the messages can be displayed along that field
  • If an unknown error key is encountered (this can happen for multi-parameter composite validations like "one of email or phone must be set") all those messages should be displayed in a central place on top or at the bottom of the UI

A validation error response looks like this:

{
  "errors": { first_name: ["is blank"] },
  "error_code": "validation_failed",
  "description": "The request parameters did not satisfy validation rules for this resource."
}

In case the request parameters input is an array, ie. {"invitations": [{ "role": null }]} the validation error response will be further grouped by the corresponding items index in the input array, for example:

{
  "errors": {
    0: { "role": ["is blank"] }
  }
}

See documentation for the user invitations endpoint for a more detailed example.

Localization

Accept-Language header

All clients must set the standard Accept-Language HTTP header explicitly and manually to the IETF language tag (en-US) or ISO639-1 (en) locale chosen by the client for client-side message localization.

The reason for this is aligning translated messages stored and shown on the client side with those from the backend, most notably on validation error messages. For example if a client supports only en and de but the device is actually set fr, if the client does not explicitly state which language it picked the backend might make a differing choice based on available backend languages or configured default fallback language.

Note that this does not affect "core" translations, which should not be fetched from the backend dynamically but be defined and used in the clients themselves.

Additionally the backend stores the user's current language to use for server-side issued user-facing communication like e-mails and push notifications.

Determining available languages

From the total pool of supported languages, only a subset is enabled for any tenant, and one of these is the default locale.

Clients must use only available locales for the tenant, so if a tenant supports en and de and has a default of de, if fr is also a MotionTools supported language a client on a device configured to be fr locale must then fall back to the default locale de, because fr is not in the enabled list.

For mobile apps, the default and supported locales are baked in the apps at compile time currently. For web clients the frontend configuration endpoint is used

Metadata

You can inject custom data within MotionTools by structuring it as metadata on supported entities.

Metadata unlocks vast integration possibilities and could be used from simple cases where an external tracking id is added to a MotionTools package to more complex cases where metadata could be used to define behavior not supported by MotionTools out of the box, such as organizing drivers into teams by criteria defined by you & stored in metadata on the user accounts.

We support metadata on the following resources:

The listed endpoints will perform a full update of the metadata, effectively replacing the old one with the newly provided one.

We also support partial metadata updates via the PATCH HTTP semantics:

Metadata added on MotionTools entities can additionally be used to search & filter objects based on the contents of the metadata. Filtering based on metadata is currently available for:

Working with CDN images

Many resources contain images URLs that should be displayed to the user. We host these images through the Cloudinary CDN at the highest available resolution and quality, i.e. collecting SVG images where possible and so on.

In order for clients to be able to use those images at the contextually required size and format cloudinary transformations must be utilized:

Take for example this cloudinary URL:

https://res.cloudinary.com/mtools/image/upload/v1587046313/production/m-tools-hailing-demo/dashboard_wallpaper-526ba6aaa06baeaf567d3a53dc41b095.jpg

In order to enforce PNG format and a 400px width, you must inject w_400,f_png into the /image/upload/TRANSFORMS/v part:

https://res.cloudinary.com/mtools/image/upload/w_400,f_png/v1587046313/production/m-tools-hailing-demo/dashboard_wallpaper-526ba6aaa06baeaf567d3a53dc41b095.jpg

Please note that Cloudinary offers client side SDKs, however we recommend not to use them because:

  • We do not use the majority of their features, like uploads, so they add bloat
  • They must be initialized with another token that needs to be managed

Instead, please just use simple string substition to inject your desired parameters the way you need them. Here's a very basic example method in Ruby:

def cloudinary_transform(url, width:, format:)
  url.sub "/image/upload/v", "/image/upload/w_\#{width},f_\#{format}/v"
end

Images have cache-busting URLs, so if they change their URL will change. Therefore, it's safe to cache them long-term.

Working with payment methods

When working with payments, you need to provide which payment method should be used.

How are payment methods configured?

  • Per tenant: This triggers overall availability of a payment method for enabling in service areas
  • Per service area: This defines actual availability of a payment method from superset of tenant payment methods in a given service area
  • On top of this, some payment methods can be configured to be manually enabled per customer on a tenant-global level

So, depending on what you want to do you must source the available payment methods from the right place so it's correct with regard to all the rules derived from the configuration defined above.

Where to get payment methods that are available to a customer?

For "My Account" settings

This is the page where a user can in general configure their stored payment methods, like credit cards and so on. It should be sorced from User Config API endpoint.

When I want to create a booking

The dedicated endpoint for Bookings Configuration should be used in that case.

Note that when wanting to create a booking as an admin on the behalf of a customer, customer_id should be provided on this endpoint. That way you'll be sure that you're fetching just the payment methods that are enabled for this customer.

When I want to change payment method on an existing booking

Use the supported_payment_methods list returned on the individual booking API response.

Tenant Configuration

Endpoints for fetching configuration for a specific MotionTools tenant

Tenant Customizations

Returns the enabled customizations (and their values, where applicable) for the tenant. The tenant is determined based on the X-Client-Version header value.

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "customizations": {
    }
}

Uploads

Endpoints for uploading files for attaching against other resources.

Upload Image

Upload images for later usage as attachments to other resources.

You need to send the file as a multipart/form-data content type and the file itself should be the upload[file] parameter, for example using curl:

curl -F 'upload[file]=@/tmp/myfile.jpg' <AUTH_HEADERS> <BACKEND_URL>

Make sure to hold on to the returned ID, you will need it later!

Permissions

Permitted when corresponding upload features are enabled

User Roles

admin customer driver org_manager
βœ… βœ… βœ… β›”
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: multipart/form-data
required
object

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "content_type": "image/jpeg",
  • "filename": "example.jpg",
  • "size": 0
}

Utilities

Utilities endpoints that help facilitate other services

Download Async Document

Generating some on-demand documents like PDFs can take considerable time, making them unsuitable to be sent synchronously as part of the original HTTP request / response cycle.

Instead, on endpoints using async documents upon completing the request you will receive an async_document_id with a 202 Accepted HTTP status code.

How to know when it is ready?

The recommended way to get notified about completion is by subscribing to the websocket notification.

Once the document is ready, this endpoint with the corresponding document ID can be requested and will return the URL where the document can be downloaded from.

Alternatively, it's possible to query this endpoint - it will respond with 422, see the Not Ready response description below. Doing it like this is very inefficient though, so please prefer going the websocket route.

Completed documents are automatically deleted after some time, so once a document is ready it should immediately be downloaded.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "async_document": {}
}

Maps

Optimize Route

This endpoint allows optimization of a route based on both existing as well as on custom stops (stops that have not been actually created yet).

This can be utilized to optimize the completion time of a booking or tour before creating it as well as when updating it later on.

Apart from creating an optimized route plan it will also return estimated times of arrival and completion. The time estimates take the at-stop durations for pickup and dropoff stops configured for each service into account and therefore for custom (new) stops additional data is required to be passed on top of plain GPS coordinates.

The endpoint accepts for both custom as well as existing stops an id. This id will then accordingly be returned on the response payload, for usage in reconciling UI state for example against the optimized route.

One of the given custom or existing stops must be defined as the start of the route, and passed via the start_id reference. Optionally, a corresponding destination may be defined by passing the destination_id parameter.

When making requests, it is mandatory to provide the target.tour boolean flag. When optimizing for a regular (customer) booking, it should be set to false, when optimizing for a tour it must be set to true. This is neccessary because in the latter case, the configuration of the service of the tour will be used for estimating at-stop durations, which can differ from the service and it's corresponding configuration on the original customer booking.

A strategy can be provided to give the optimizer hints about the order of stops.

Supported strategies are:

  • dropoff_after_pickup_in_sequence will place applicable dropoffs after its (by booking) related pickup in the route
  • all_pickups_before_all_dropoffs will place pickups before any dropoff in the route

Be aware that, when using strategies while providing start and/or destination IDs, the strategy will not be applied to the start and/or the destination ID.

The globally configured vehicle type and it's speed will be taken into account for the optimization.

⚠ Deprecation warning

Version 2 of this endpoint is currently still supported, but will be sunset in February 2023. Please use the (default) version 3 instead.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
One of
Deprecated
required
object
Deprecated

Responses

Request samples

Content type
application/json
Example
{
  • "route_optimization": {
    }
}

Response samples

Content type
application/json
{
  • "route_optimization": {
    }
}

Estimate route time of arrival and distance

This endpoint estimates the time of arrival distance for each provided stop to the first stop.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "route_estimate": {
    }
}

Response samples

Content type
application/json
{
  • "route_estimate": {
    }
}

Signup

This section describes endpoints for user account signup & signin

Signup with E-Mail

Using this endpoint a user can perform a signup using an e-mail address and a chosen password.

  • TODO: Explain invitations

  • TODO: Explain opt-ins

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "refresh_token": "string",
  • "expires_in": 86400
}

Session

Endpoints relating to authentication

Sign In with E-Mail

Allows signin using known e-mail and password combination

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "refresh_token": "string",
  • "expires_in": 86400
}

Refresh Access Token

Acquire a new short-lived access token from long-lived refresh token

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
refresh_token
required
string

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "94245008a695791b5f7b20621e842c8542654d0f"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 86400
}

Sign Out

Sign out of current session, expiring active access, refresh and push notification tokens. If the user is not logged in or uses expired access token, the endpoint will return 401 Unauthorized error.

query Parameters
trigger
string or null
Example: trigger=signout-button-pressed

Optional indicator of what triggered this signout

unauthorized_url
string or null

When a signout was a force-signout-on-401, optionally the URL requested that responded with 401 can be provided here for further investigation

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "error_code": "unknown_tenant",
  • "description": "An english plain text description of the problem"
}

Password Reset

Functionality for enabling users to reset their forgotten account passwords

Reset Password

Allows to request a new password via e-mail. Successful submission will send further instructions to the provided address.

Note that to prevent data leakage this endpoint will always report success, even if an account does not actually exist.

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "success": true
}

Change Password

Allows to set a new password using the token provided in reset password e-mail. Normally the token will be embedded in a deep link to the web dashboard so the user does not have to fill it manually.

The token is valid for 24 hours.

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "error_code": "unknown_tenant",
  • "description": "An english plain text description of the problem"
}

Push Tokens

Push notifications are used to notify users about events that happened in the background or when the app is off-screen.

We are using Firebase cloud messaging as a third-party service for sending them.

To be able to receive push notifications, clients must register a Firebase token for the user.

Once the token is registered it's attached to the current session (i.e. current authentication token). This implies that when the user logs out, the token is also removed.

Store push token

Allows to store a firebase push notifications token for this user, which will subsequently be used for delivering push notifications.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
token
required
string

The firebase push token value to be stored

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Remove push token

Remove a registered push notification token. The push token removed is the one tied to the current application session (identified by the access token).

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Account

Endpoints related to the currently authenticated user account

User Account

Get details of currently signed in user account

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

Show Current Flags

Returns flags set on the active user's account. Flags are configuration toggles that can be set by admins to enable some specific features for a user the flag is set on.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "flags": {
    }
}

User Config

Via this endpoint clients can dynamically pull information about user-specific configuration for the authenticated user.

At the moment you can find a list of all supported payment methods for logged in user. This configuration is service area agnostic, so it should be used only for managing payment methods in the user account configuration page, not for making actual bookings.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

Account Features Status

Based on the tenant configuration and user role different account features might be enabled for a user.

On mobile apps and the web dashboard each "feature" maps to a dedicated screen that can be shown during onboarding if applicable and on the account menu accessible via the sidebar.

During onboarding the expected order of screens is implied by the order returned in this list.

To only confirm that the current user has completed onboarding, the onboarding_complete flag on the User Account endpoint can be used.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "account_features": [
    ]
}

Verify Email

Use this endpoint when email verification is required during onboarding process for particular user.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
verification_code
required
string

4 digit code sent to verify email address

Responses

Request samples

Content type
application/json
{
  • "verification_code": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Request Email Verification Code

Use this endpoint when you didn't receive an email with verification code or it has already expired.

NOTE for testing environments verification code is set to "1234"

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Show User Flags

Allows to view a user's configuration flags.

Flags are configuration toggles that can be set by admins to enable some specific features for a user the flag is set on.

For the currently active user's own flags please use the Show Flags endpoint instead.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "flags": {
    }
}

Response samples

Content type
application/json
{
  • "flags": {
    }
}

Update User Flags

Allows to update a user's configuration flags.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
user_id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "flags": {
    }
}

Response samples

Content type
application/json
{
  • "flags": {
    }
}

Profile

Endpoints related to the user's profile.

Show Profile

Returns current values set on the user's profile

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "profile": {
    }
}

Update Profile

Allows to update the current user's profile.

Partial updates (e.g. just first_name) are not supported.

Permissions

Permitted when the Profile Details feature is enabled.

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object or null (UserProfile)

User's profile details.

  • Field availablity is configurable per tenant
  • The whole feature can be disabled for specific roles

Responses

Request samples

Content type
application/json
{
  • "profile": {
    }
}

Response samples

Content type
application/json
{
  • "profile": {
    }
}

Update Profile as Admin/Org. Manager

Allows to update user's profile by admin or org manager.

Partial updates (e.g. just first_name) are not supported.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object or null (UserProfile)

User's profile details.

  • Field availablity is configurable per tenant
  • The whole feature can be disabled for specific roles

Responses

Request samples

Content type
application/json
{
  • "profile": {
    }
}

Response samples

Content type
application/json
{
  • "profile": {
    }
}

Opt-Ins

These endpoints allow signed in users to fetch current opt-ins status as well as updating them.

Please see also the corresponding signup feature detection endpoint and opt_ins params on signup.

  • Required opt-ins cannot be opted-out of again

  • Disabled opt-ins must not be shown to the user

Please make sure that you write your code in a way that newly introduced opt-ins do not crash your code and are instead either silently ignored or just display the type raw without translation if enabled as a fallback

View Opt-In Status

Allows to retrieve opt-in configuration and status for the currently authenticated user account.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "opt_ins": [
    ]
}

Update Opt-Ins

Update opt-ins for the current user. Trying to disable a required opt-in will result in a validation error. Sending opt-ins that aren't enabled for this tenant will be ignored.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "opt_ins": {
    }
}

Response samples

Content type
application/json
{
  • "opt_ins": [
    ]
}

Invoice Address

Endpoints for managing invoice address of a user.

Show Invoice Address

Show an invoice address for the current user.

Permissions

Allowed when the feature is enabled for this user

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "address": {
    }
}

Update Invoice Address

Set or update invoice address for the current user.

Partial updates for required fields is not allowed.

Permissions

Allowed when the feature is enabled for this user

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object (UserInvoiceAddressRequest)

User's invoice address.

Some fields are optional and some are required. To find out which fields are required, you can use [Account Features Status](#operation/UserAccountFeatures] endpoint.

Responses

Request samples

Content type
application/json
{
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "address": {
    }
}

Update Invoice Address as Admin/Org. Manager

Set or update invoice address for the current user as admin or org. manager.

Partial updates for required fields is not allowed.

This endpoint supports PATCH semantics, meaning that you can send partial request objects and only the provided fields will be updated. Sending a null value for one of the fields will set the value of that field to null if the field is nullable.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object (UserInvoiceAddressRequest)

User's invoice address.

Some fields are optional and some are required. To find out which fields are required, you can use [Account Features Status](#operation/UserAccountFeatures] endpoint.

Responses

Request samples

Content type
application/json
{
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "address": {
    }
}

Customer's Vouchers

Endpoints for managing Vouchers for current customer.

Vouchers attached to current user

This endpoint returns the vouchers attached to the current user.

Current user must be a customer.

Permissions

When Voucher feature is enabled, accessing this endpoint is permitted for customer's vouchers and any voucher for admins.

User Roles

admin customer driver org_manager
βœ… βœ… β›” β›”
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "meta": {
    }
}

Attach Voucher to current user.

Attaches a voucher to the current user.

Current user must be a customer.

Permissions

When Voucher feature is enabled, accessing this endpoint is permitted for customer's vouchers and any voucher for admins.

User Roles

admin customer driver org_manager
βœ… βœ… β›” β›”
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
code
required
string (code)

Code for the voucher that customers can use

Responses

Request samples

Content type
application/json
{
  • "code": "DISCOUNT10"
}

Response samples

Content type
application/json
{
  • "customers_voucher": {
    }
}

Detach Voucher from current user.

Detaches a voucher to the current user.

Current user must be a customer.

Permissions

When Voucher feature is enabled, accessing this endpoint is permitted for customer's vouchers and any voucher for admins.

User Roles

admin customer driver org_manager
βœ… βœ… β›” β›”
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Adding Users

Endpoints for adding new user accounts

Create user

New customers can be directly created by admins using this endpoint instead of having to sign up themselves. This is mostly for B2B cases and "call center order creation" kind of customer relationships.

When the user cannot be created due to a conflict the pre-existing other user's id will be returned in the 409 conflict response payload.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "user": {
    }
}

Invite users

This endpoint enables the addition of non-customer users into the system by preparing their accounts and sending an invitation e-mail.

Following this invitation the users can simply sign up for an account using the generic sign up endpoint, but will end up in their newly assumed role as driver, org. manager, etc.

When inviting new admins, organization will be ignored.

Organization ID shouldn't be passed if this endpoint is used by organization manager. In that case, the users are assigned the organization manager's organization automatically. For now, we only allow org. managers to invite drivers to their organizations, so that is only allowed value for the role.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "invitations": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "invitations_count": 0
}

Managing Users

Endpoints for managing existing user accounts

Account Features Status

This endpoint allows admins and org managers to check the current account features status of a given user.

By that, it equivalent of the endpoint for the user currently signed in as, but for any user visible to the requesting user.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "account_features": [
    ]
}

List Users

List user accounts

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
query Parameters
page
integer
Example: page=3

Requested page number for pagination

limit
integer
Example: limit=50

Per-page limit for pagination

pagination
string
Enum: "simple" "full"

Mode of pagination that should be used:

  • simple - only returns whether there is next/prev pages are available and doesn't return count info
  • full - returns complete pagination info with the counts of total results and total pages, and is more expensive
search
string
Example: search=Widgets

Search query string

object

Allows filtering results additionally. Not all filters are available to all roles.

order_by
string
Default: "created_at"
Value: "created_at"

Allows to request what property to sort the results by

direction
string
Default: "desc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "meta": {
    }
}

Show a user

Fetches and displays the user with given ID

Permissions

For drivers and customers only available on their own accounts

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

Anonymize User

Anonymize the user's data, which includes anonymizing email and stops' locations, as well as deleting the user from Stripe. This endpoint is only available to admins.

Please note that the actual data removal happens asynchronously, so success response does not confirm successful anonymization. Anonymization could fail for example if a driver is anonymized while still being on an ongoing booking booking.

Permissions

Permitted unless this is an internal system user like the dispatch customer

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Change User's metadata

Update the given user's metadata, replacing any existing metadata on the user.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "success": true
}

Partially Change User's Metadata

Update the given user's metadata for the given keys, preserving any metadata keys that were not sent.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object (Metadata)

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "success": true
}

Block user

Allows blocking a user from accessing the platform. Only accessible to org_manager and admin users.

Whether the authenticated user can perform this on a given user is indicated on the users endpoint by the blockable flag.

When executed, a number of additional checks will take place, for example whether the user still has unfinished bookings. When one of the conditions applies the blocking will fail and a corresponding error will be returned on the response, indicating the reason.

Upon blocking, a number of cleanup tasks will also be executed. For example, drivers that are still online will get any claimed scheduled bookings unclaimed again and will be sent offline, elegible customer bookings and packages will be automatically cancelled etc.

After successfull blocking, all active sessions and API tokens of this user are removed and new signins are prevented until manually unblocked again.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Unblock user

Allows blocking a user from accessing the platform. Only accessible to org_manager and admin users.

Whether the authenticated user can perform this on a given user is indicated on the users endpoint by the unblockable flag.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Export Users as CSV

Export user data in CSV format.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
query Parameters
search
string
Example: search=Widgets

Search query string

object

Allows filtering results additionally. Not all filters are available to all roles.

order_by
string
Default: "created_at"
Value: "created_at"

Allows to request what property to sort the results by

direction
string
Default: "desc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
text/csv
id,email,created_at,first_name,last_name,phone_number,birthday,invoice_address,marketing_opt_in
c3d2777c-c20c-5a1c-a1a9-7a247bc8d0cc,[email protected],2020-10-08 13:29:07.127003,Petra,Meier,+49123123123,,"",
9a5ce511-e5d9-5487-9a5d-80486f6e47f6,[email protected],2020-10-08 13:29:07.127003,Peter,Meier,+49123123123,,"",

Managing Opt-Ins

Endpoints for managing user account opt-in settings

View User Opt-Ins

Enables admins to view current status of opt-ins for any user. This can be especially useful when used in conjunction with opt-in webhooks to synchronize opt-in status with external systems via the API.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "opt_ins": [
    ]
}

Payment Methods

These endpoints are used for handling payment methods available to a user.

Manually activated payment methods

Payment methods can be configured on a tenant level to be enabled manually, which means they will only be available to a customer when they were enabled for them by an admin.

View payment methods

Fetch currently activated payment method for the user together with some meta information about tenant supported and activatable payment methods.

This endpoint is only available to admin users

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "enabled_payment_methods": [
    ],
  • "manually_activated_payment_methods": [
    ],
  • "currently_activated_payment_methods": [
    ]
}

Update payment methods

Replace currently activated payment method for the user. This only applies to payment methods that are configured to be manually activated for this tenant.

This endpoint is only available to admin users

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "user": {
    }
}

Response samples

Content type
application/json
{
  • "enabled_payment_methods": [
    ],
  • "manually_activated_payment_methods": [
    ],
  • "currently_activated_payment_methods": [
    ]
}

Muting Driver Requests

These endpoints allow admins to mute and unmute drivers.

Muted drivers are not considered in instant matching and do not receive scheduled booking claimable push notifications. This can help reduce notification noise and matching efficiency when using different booking systems in parallel.

Mute driver requests

Mute driver requests for a given driver ID.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

Unmute driver requests

Unmute driver requests for a given driver ID.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

Managing Organizations

Organization Defaults

Returns default values for the fields of an organization as well as additional tenant-specific configuration hints that are used for building the user interface according to the configuration.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "defaults": {
    },
  • "configuration": {
    }
}

List all Organizations

Returns a list of organizations visible to current user

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
query Parameters
page
integer
Example: page=3

Requested page number for pagination

limit
integer
Example: limit=50

Per-page limit for pagination

pagination
string
Enum: "simple" "full"

Mode of pagination that should be used:

  • simple - only returns whether there is next/prev pages are available and doesn't return count info
  • full - returns complete pagination info with the counts of total results and total pages, and is more expensive
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "meta": {
    }
}

Create Organization

Allows creation of a new organization

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "organization": {
    }
}

Response samples

Content type
application/json
{
  • "organization": {
    }
}

Show Organization

Show a specific organization.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "organization": {
    }
}

Update Organization

Allows modifying base properties of an existing organization

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "organization": {
    }
}

Response samples

Content type
application/json
{
  • "organization": {
    }
}

Changing Driver's Organization

Endpoints for changing driver's organization

Change Driver's Organization

Change driver's organization to the given one. The given organization_id must be visible to the acting user, i.e. if org. manager is changing driver's organization, he must be a managing user for that organization.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid> (uuid)

UUID identifier of the resource

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Request Body schema: application/json
organization_id
required
string <uuid> (uuid)

UUID identifier of the resource

Responses

Request samples

Content type
application/json
{
  • "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6"
}

Response samples

Content type
application/json
{
  • "success": true
}

Feature Detection

Endpoints for detecting the tenant-specific configuration and features of bookings

Bookings configuration

Using this endpoint clients like our web dashboard can dynamically pull required information about bookings-specific configuration.

This configuration can be fetched for a particular service area by sending the query parameter with a list of lat, lng pairs for the stops, or you could omit this param and not sending anything which will result in general config that has no service area related info included.

The desired service's id should be given, otherwise the response will be for the default service.

This endpoint can be used with or without authentication. Unauthenticated use qualifies as guest-mode. Usage with authentication might have slightly different response values, e.g. different payment methods.

When requesting this endpoint as an admin to book on behalf of a customer customer_id parameter should also be passed to ensure that things like customer-specific payment methods are reflected correctly.

Authorizations:
BearerAuth
query Parameters
object

Query parameters required to pinpoint the specific configuration to return

lat
string
Deprecated

Pickup latitude. Deprecated due to changes to stop validation rules, please use full stops object.

lng
string
Deprecated

Pickup longitude. Deprecated due to changes to stop validation rules, please use full stops object.

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "hailing": {
    }
}

Hailing Driver configuration

This endpoint allows driver clients to detect feature configuration that can change at runtime.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
β›” β›” βœ… β›”
Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "hailing": {
    }
}

Capabilities configuration

Lists the available capabilities and their corresponding available options and configuration for the current tenant required to be chosen to make a booking or go online as a driver.

The returned details about capabilities allow to construct the whole capabilities screen dynamically.

Please note that capabilities and their respective values that are not enabled are not available for choice when creating bookings or submitting capabilities as a driver when going online.

Authorizations:
BearerAuth
query Parameters
object
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
[]

Services configuration

This endpoint allows inspecting all Services configured for the tenant.

Clients must display offered services and their capabilities for new bookings according to the information provided by this endpoint.

Usually a tenant will only have the default service, however even that might only include some specific subset of the overall capabilities of the tenant as returned by the Capabilities introspection endpoint.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{}

Failure Reasons Detection

This endpoint allows clients to introspect available failure reasons.

Authorizations:
BearerAuth
header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "failure_reasons": [
    ]
}

Price Query

Allows to query the price for given booking route, capabilities and (optional) voucher code.

Prices are returned as integers and should be formatted accordingly.

Matrix prices can have components which are available under components field. Only non-zero value for a component should be shown on the UI.

The desired service's id should be given, otherwise the response will be for the default service.

When requesting this endpoint as an admin to book on behalf of a customer customer_id parameter should also be passed to ensure that things like voucher usage limits are respected correctly.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
query Parameters
required
object

Query parameters required to pinpoint the specific configuration to return

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "price": {
    }
}

Service area scheduling configuration

This endpoint allows to fetch scheduling config for a service area that matches given stops list. The provided config can be used to construct timeslots on the client. Please make sure to take into account the applicable time zone for any calculations.

When using this endpoint for fetching packages related info, you should provide a pickup_place_id and destination as query params instead of stops.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
query Parameters
object

Query parameters required to pinpoint the specific configuration to return

header Parameters
Accept
string
Example: application/json

The requested response body content type. At this time we only support application/json

Accept-Language
string
Example: en

Locale code of the preferred language of the client. See Localization for further details.

Content-Type
string
Example: application/json

Indicates the content type of the request body, if applicable. We support application/json,

application/x-www-form-urlencoded and multipart/form-data.

X-Client-Version
string
Example: ACME Inc. iOS Customer/1.3.0

Indicates the client that is making the request. See Client Identification

Responses

Response samples

Content type
application/json
{
  • "scheduling_config": {