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

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: 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.

Optionally, a scheduled_at ISO8601 datetime can be defined as the starting time for the optimized route, calculations will then take place for the given time. When omitted, this defaults to the current time. Beware of keeping consistent timezones!

The earliest_arrival_at and latest_arrival_at of existing stops will be taken into account. You can set them on stop creation or modify them later using the Update Arrival Times endpoint. For custom stops you can equally optionally pass the desired values. They are not required in combination, so it's ok to just define one of them when applicable.

When stops have earliest arrival defined, this can lead to neccessary waiting times for the driver, which are indicated on the response.

When stops have a latest arrival defined which cannot be satisfied with the given constraints, the stop will not be planned for the route but instead returned in the unassigned collection.

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
required
object

Responses

Request samples

Content type
application/json
{
  • "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
}

Re-send welcome e-mail

Allows re-delivery of the welcome e-mail to the given customer.

Permissions

Permitted only on customer accounts which don't have their e-mail verified and when the welcome e-mail is actually enabled.

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

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": {
    }
}

Create & Update Bookings

Endpoints for creating and updating bookings

Create a Booking

This endpoint is available to both customers and admins. If used by a customer, then the booking will be created for the signed in customer.

Special error cases

Due to the complexity of making a booking and cross-dependencies based on the booking's properties there's a bunch of specialized validation error cases that a booking can end up with.

Since the various validations depend on previous steps passing successfully the backend will always return only one of those, the one the validation chain has failed on, so fixing the error on hand will not necessarily fix the entire booking's validity.

Those errors and their messages are not translated and are meant for internal / development uses, the UX flow on the client side should ensure that the pre-conditions are legitimately met upfront.

The error codes that can be returned can be found inside the 422 booking error response schema description below.

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
As Customer (object) or As Admin (object)

Responses

Request samples

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

Response samples

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

Order booking's stops

Update the order of the booking's stops. The stops must be either in approaching or scheduled state. In case the operation is done by the customer, the booking has to be in the to_bo_dispatched state. The driver can only change the order of the stops when the booking is en_route.

In case the re-order is done by admin or org. manager, then the booking must be in one of the following states:

  • scheduled
  • to_be_dispatched
  • claimed
  • pickable
  • searching_provider
  • pending_provider
  • en_route

The permission for this action can also be introspected from the booking's compact and standard view under permissions.order_stops key.

Permissions

Permitted for admins and org. managers when the tour/booking is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route. For drivers it's permitted only if it's en_route and the driver is the one working on it. For customers it's permitted only while the booking is in to_be_dispatched state.

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
path Parameters
booking_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
Array of objects non-empty

Responses

Request samples

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

Response samples

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

Update Booking

Note that there are limitations on which bookings can be updated after creation. Please use the editable property on booking objects to evaluate whether the update operation is available for this booking.

A change of scheduling mode is not permitted, so converting instant to scheduled bookings or vice versa is not allowed.

Permissions

Only allowed on regular bookings or regular tours that are in to_be_dispatched, pickable, scheduled, searching_provider, pending_provider state and don't have a voucher.

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
{
  • "booking": {
    }
}

Response samples

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

Change Booking's Metadata

Set booking's metadata, replacing any existing metadata on the booking.

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
{
  • "booking": {
    }
}

Response samples

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

Partially Change Booking's Metadata

Update the given booking'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
{
  • "booking": {
    }
}

Response samples

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

Change booking's automatic scheduling

Allows to change a boooking's schedule_automatically_at value to a new ISO8601 timestamp or to null to deactivate automatic scheduling.

When a booking has this set and manual dispatching is enabled, it will automatically be transitioned from to_be_dispatched status via the schedule event to become visible to eligible drivers based on the applicable driver request distribution configuration and the booking's scheduling properties.

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
{
  • "booking": {
    }
}

Response samples

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

Perform a transition on a booking

Transitions referenced booking using the given event.

See available_transitions in the All Bookings response for valid events of current user.

State machine graph for the booking's state
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
{
  • "event": {
    }
}

Response samples

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

Update driver earnings

Update earnings indicated to a booking or tour's driver.

By default, the earnings are always unset on any tour or booking. By using this endpoint, an amount and currency can be assigned, which will be visible to the driver in the driver app and also can be used later on for building reporting and analytics integrations using the stored values.

If you want to remove a previously assigned earnings value from a booking or tour again, simply send null as the currency and/or amount.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
booking_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
{
  • "earnings": {
    }
}

Response samples

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

Booking Visibility

Force-assign driver

Allows to force-assign a driver to an instant booking.

When this operation is performed on a booking that is in instant matching (searching_provider or pending_provider state) the driver will be assigned to this booking and the booking goes immediately to `en_route.

When it's preformed on a booking that is in pickable state, the booking will be picked on a behalf of the driver.

For a booking in scheduled state, the scheduled booking will be claimed on behalf of the driver.

For a booking in en_route state, the drivers will just be swapped.

This operation is available to visible bookings for admins and org_managers.

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

UUID identifier of the resource

driver_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
}

Add preferred drivers

Mark certain drivers as preferred to take the booking. If the provided list is empty, then no driver is preferred and matching will be done automatically.

This operation is available to visible bookings for admins and org_managers.

When the booking has managing_organizations and a driver ID is given that does not belong to any of them, we will respond with a driver_not_associated failure.

Permissions

Only permitted when booking status is not in:

  • done
  • paid
  • cancelled

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
booking_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
{
  • "booking": {
    }
}

Response samples

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

Update managing organizations

Update booking's managing organizations.

The availability of this operation can be found by inspecting the booking's permissions.update_managing_organizations property.

In case that the booking has a driver already assigned, or it has preferred drivers set, the managing organizations can be only set to the organizations that correspond to these drivers.

You can also unset the managing organizations by sending an empty array.

Permissions

Available only when the booking is not in partially_dispatched, dispatched or one of the terminal states (processing_payment, done, paid or cancelled).

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
booking_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
Array of objects

List of organization IDs to be set as managing organizations for this booking.

Responses

Request samples

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

Response samples

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

Interact with Stops

Endpoints in this group allow making changes to a stop once it's already present in our system as well as transitioning it's state.

Insert custom stop into existing booking

Add a new, custom stop into an existing regular booking.

The stop can't be inserted before a stop that is not in either approaching or scheduled state.

The user must provide either the stop's coordinates or the the ID of a place. The referenced place must be visible to the user.

The actual newly created stop will be returned under the stop key in the response.

Permissions

Permitted for admins and org_managers when the booking or tour is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state, for customers when their booking is in to_be_dispatched state.

Not permitted for package tours.

User Roles

admin customer driver org_manager
βœ… βœ… β›” βœ…
Authorizations:
BearerAuth
path Parameters
booking_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
position
required
integer >= 1
required
object (NewCustomHailingBookingStop)

Responses

Request samples

Content type
application/json
{
  • "position": 3,
  • "stop": {
    }
}

Response samples

Content type
application/json
{
  • "stops": [
    ],
  • "stop": {
    }
}

Update Location

Update a stop's location, including the GPS coordinates and other address data.

As a stop always must have GPS coordinates, you can trigger a geocoding on an existing stop by explicitly sending lat: null, lng: null alongisde the desired address data, and geocoding will be performed accordingly.

You can check whether permission to update is available for a specific stop by inspecting the corresponding permissions.edit_location property of the stop contained in the booking's compact and standard payloads, for example on Show Booking.

If the GPS coordinates of the stop have changed by the update, the related booking's...

  • service area will be re-evaluated based on the configured stop validation rules
  • price will be re-calculated if the booking has a price - overwriting any custom price that may have been applied before

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

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.

Permissions

Restrictions apply to when the location data may still be edited:

  • Not available on stops that are linked to places
  • Only available on scheduled, approaching, and failed stops
  • The stop must not have any package interactions attached to it (only applicable when using the packages extension)
  • For customers, editing the location is not permitted on dispatched, partially_dispatched, or en_route bookings

User Roles

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

UUID identifier of the resource

stop_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
{
  • "location": {
    }
}

Response samples

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

Update Contact Details

Update contact information on a stop.

You can check whether permission to update is available for a specific stop by inspecting the corresponding permissions.edit_contact property of the stop contained in the booking's compact and standard payloads, for example on Show Booking.

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

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.

Permissions

Available to admins and customers on stops that don't have package interactions.

User Roles

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

UUID identifier of the resource

stop_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
{
  • "contact": {
    }
}

Response samples

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

Update Stop Properties

This endpoint allows adjusting some general properties of a stop, namely type, flow, maximum_driver_distance_meters, and priority.

  • Customers can only update the type of a stop
  • Admins cannot update the type or flow of stops that have package interactions on them

You can check whether permission to update is available for a specific stop by inspecting the corresponding permissions.edit_properties property of the stop contained in the booking's compact and standard payloads, for example on Show Booking.

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

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.

Permissions

Permitted while a stop is scheduled, approaching, or failed

User Roles

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

UUID identifier of the resource

stop_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 (UpdateStopPropertiesRequest)

Responses

Request samples

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

Response samples

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

Update Arrival Times

Update earliest and latest arrival times on a stop.

You can check whether permission to update is available for a specific stop by inspecting the corresponding permissions.edit_arrival_times property of the stop contained in the booking's compact and standard payloads, for example on Show Booking.

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

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.

Permissions

Permitted while a stop is scheduled, approaching, or failed

User Roles

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

UUID identifier of the resource

stop_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
{
  • "arrival_times": {
    }
}

Response samples

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

Update Additional Information

Update additional information and order images on a stop. The order images must consist of image IDs already present on this stop as well as any unattached uploads of the acting user uploaded via Upload Image.

You can check whether permission to update is available for a specific stop by inspecting the corresponding permissions.edit_additional_information property of the stop contained in the booking's compact and standard payloads, for example on Show Booking.

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

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.

Permissions

Permitted while a stop is scheduled, approaching, or failed

User Roles

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

UUID identifier of the resource

stop_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
object (UpdateStopAdditionalInformationRequest)

Responses

Request samples

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

Response samples

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

Update Custom Content

Update stop's custom content.

You can check whether permission to update is available for a specific stop by inspecting the corresponding permissions.edit_content property of the stop contained in the booking's compact and standard payloads, for example on Show Booking.

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

Permissions

Available for any stop in scheduled, approaching or failed state and the booking/tour is not in a final state (like cancelled or paid).

User Roles

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

UUID identifier of the resource

stop_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
{
  • "stop": {
    }
}

Response samples

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

Update Stop's Metadata

Updates given stop's metadata, replacing any existing metadata on the booking.

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

Permissions

Permissions to access this endpoint.

User Roles

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

UUID identifier of the resource

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
{
  • "stop": {
    }
}

Response samples

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

Partially Update Stop's Metadata

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

If the updated stop has a parent it was dispatched from, the parent will be updated as well. If the updated stop has a dispatched child, the child will equally be updated as well.

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.

Permissions

Permissions to access this endpoint.

User Roles

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

UUID identifier of the resource

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
{
  • "stop": {
    }
}

Response samples

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

Bulk Update Stop's Groups

This endpoint updates all referenced stops' group that belong to this booking. Related stops (child or parent stops) are updated as well.

Note: All referenced stops must be in scheduled state.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
booking_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
Array of objects

Responses

Request samples

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

Response samples

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

Remove stops from a booking

Remove approaching or scheduled stops from a booking.

Permissions

Permitted for admins and org_managers when the booking is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state, for customers when their booking is in to_be_dispatched state.

User Roles

admin customer driver org_manager
βœ… βœ… β›” βœ…
Authorizations:
BearerAuth
path Parameters
booking_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
Array of objects non-empty

Responses

Request samples

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

Response samples

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

Perform Stop Transition

Triggers the event transition for the given stop.

Available stop transitions can be found by inspecting the available_transitions stop property on the booking to which the stop belongs.

State machine graph for the stop's state

Permissions

Available to admins and org managers as well as when the user is the assigned driver on this booking. The actual transitions that can be performed depend on stop status and are indicated on the available_transitions property of a stop.

User Roles

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

UUID identifier of the resource

stop_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
{
  • "event": {
    }
}

Response samples

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

Complete stop

Allows drivers to complete a stop, including completing a stop after an intermittent internet connectivity outage once connectivity is back.

This endpoint is meant to be used in conjunction with the booking.stops.completion_requirements data returned on standard and compact booking return values, which indicate the information to be gathered while fulfilling the stop.

This endpoint is available both when a stop is approaching and when it's already arrived. When submitted while the stop is still approaching, the necessary transition to arrived will be performed automatically. Similarly, if applicable, the handling of the waiting_for_proof status cycle on the stop will also be handled automatically, so a successful submission will inevitably lead to a done stop from both approaching and arrived.

Generally, on the UI side the behaviour should be handled like this:

  • When a driver taps arrived, but the API call fails due to missing internet, start saving all subsequent information locally. Otherwise, in a success case proceed as usual.
  • When a driver completes a stop by providing all necessary information, including the stop proofs as configured as well as package interaction outcomes if applicable, try to submit the data. In case this fails due to missing internet connection, the driver should be shown a "waiting to go online" screen instead of the regular stop completion flow.

For the arrive transition, please note that a stop with a flow of single_step will completely skip the arrived stage of a stop, so no proofs or package interaction outcomes will be collected in this case - therefore, for such a stop the waiting to go online screen should be shown immediately after the (failed) swipe of the "arrived" button.

Our API is the authoritative source of truth, so in case a race condition between the state that was present on the device at time of losing connectivity and the central state occurs, such as a booking getting cancelled or a stop being moved in the order by an admin for example, the stop completion data stored must be thrown away on the driver app side and the current state restored from the API.

Such a race condition can, depending on the case, materialize in 403, 404, 409 or 422 responses.

➑ See also the sibling Fail Stop endpoint

Permissions

Available when the user is the assigned driver on this booking and the stop is in approaching or arrived status

User Roles

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

UUID identifier of the resource

stop_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

Since an offline stop completion submission would arrive at a later point in time, to keep booking event history data consistent we require the tracking and submission of the corresponding timestamps as part of stop completion, in order to later on, for example, calculate correct at-stop durations and so on.

Array of objects or null (StopCompletionPackageInteractions)

Holds information about individual package interaction outcomes. Only applicable in case package interactions are present on this stop.

For completing a stop, the interactions are required to be given.

For failing a stop, they must only be given if the stop is already in an arrived status. When failing while approaching, the all package interactions will always be marked as a failure.

object or null

The proof image upload IDs, signature upload ID and/or textual proof (see note property) to be assigned to this stop.

This feature is configured per service and stop type, please refer to the completion_requirements.proofs property on stops to identify the specific configuration and requirements that applies to this stop.

Responses

Request samples

Content type
application/json
{
  • "package_interactions": [
    ],
  • "proofs": {
    },
  • "timestamps": {
    }
}

Response samples

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

Fail stop

Allows drivers to fail a stop, including failing a stop after an intermittent internet connectivity outage once connectivity is back.

This endpoint is meant to be used in conjunction with the booking.stops.completion_requirements data returned on standard and compact booking return values, which indicate the information to be gathered while fulfilling the stop.

This endpoint is available both when a stop is approaching and when it's already arrived, but only if the failing of stops is enabled for the underlying tenant.

➑ See also the sibling Complete Stop endpoint

Permissions

Available when the user is the assigned driver, an admin or an org_manager on this booking and the stop is in approaching or arrived status

User Roles

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

UUID identifier of the resource

stop_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

Since an offline stop completion submission would arrive at a later point in time, to keep booking event history data consistent we require the tracking and submission of the corresponding timestamps as part of stop completion.

Array of objects or null (StopCompletionPackageInteractions)

Holds information about individual package interaction outcomes. Only applicable in case package interactions are present on this stop.

For completing a stop, the interactions are required to be given.

For failing a stop, they must only be given if the stop is already in an arrived status. When failing while approaching, the all package interactions will always be marked as a failure.

Responses

Request samples

Content type
application/json
{
  • "package_interactions": [
    ],
  • "timestamps": {
    }
}

Response samples

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

Submit Delivery Proofs Deprecated

This endpoint is only available if the tenant requires proof images and when the stop is in waiting_for_proof state.

Proof images can be uploaded to both pickup and dropoff stops.

Once the images are uploaded, the state machine automatically transitions to done state for this stop.

⚠ Deprecated in favor of the Complete stop endpoint

Permissions

Available when the user is the assigned driver on this booking and the stop is in waiting_for_proof status

User Roles

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

UUID identifier of the resource

stop_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 (StopProofSubmission)

The proof image upload IDs, signature upload ID and/or textual proof (see note property) to be assigned to this stop.

This feature is configured per service and stop type, please refer to the completion_requirements.proofs property on stops to identify the specific configuration and requirements that applies to this stop.

Responses

Request samples

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

Response samples

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

Advanced Dispatching

Our advanced dispatching feature set allows for grouping and splitting regular bookings into one or many tours that a driver would then execute.

For example, this can be used to:

  • Bundle several delivery orders into a single route executed by a driver
  • Split bookings into several tours, for example if you first want to bring picked up goods to a central warehouse, from which you then separately deliver them to their final destination in a separate route

The various API endpoints in this section allow for granular control over tours, from their creation to performing modifications, even while a driver is already en route on a tour.

Create Empty Tour

Allows creation of an empty regular tour, which can subsequently be filled by...

Empty tours are always created in to_be_dispatched status regardless of the manual dispatching configuration on the default hailing service, as an empty tour cannot be handed to drivers. It also cannot be manually scheduled while it remains empty - it will only become possible to pass it to drivers once at least one stop exists on the tour.

Only the service_area_id to create the tour in is required. For requested_capabilities we will default to the smallest enabled capabilities for the default hailing service when not given.

For scheduled_at we will take the next available time when not given - now if instant scheduling is enabled on the default hailing service, and the next available scheduled time according to the opening hours for the service area if only scheduled is enabled.

⏰ Please note that we will automatically cancel tours that remain empty 1 hour after their creation.

πŸ’‘ If you already have customer bookings that you want to dispatch into tours, use the Dispatch Stops into Tour endpoint instead.

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 (CreateEmptyTourRequest)

Responses

Request samples

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

Response samples

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

Dispatch stops into a tour

Dispatch multiple stops from different bookings into a single tour.

A booking can be partially dispatched into a tour, i.e. a subset of stops can be provided when dispatching it. If all of the booking's stops are dispatched, then the booking will be marked as dispatched.

Admins can always dispatch, while org managers can only dispatch if one of their managed organizations is defined on the source bookings via the managing organizations feature.

Whether a source booking is eligible for this feature by this user is indicated via the mergeable flag on the bookings schema.

πŸ’‘ If you want to start with an empty tour instead, to subsequently fill it with stops, use the Create empty tour endpoint instead.

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
scheduled_at
required
string (scheduled_at_or_now_or_from_earliest)

ISO8601 Date and time for when the booking is to be scheduled.

It can also be literal string now to create instant booking if configured, or from_earliest_booking, to schedule based on earliest included booking that is being merged

required
Array of objects (ExistingHailingBookingStop)
additional_information
string or null (additional_information)

Additional information for the booking.

name
string (Booking's name) <= 20 characters

Name of the booking, only visible to non-customers.

object (requested_capabilities)

Requested capabilities for the booking.

schedule_automatically_at
string or null <date-time> (schedule_automatically_at)

Optional ISO8601 timestamp. When applied to on a manually dispatched booking (status to_be_dispatched), the booking will automatically be scheduled to be visible by drivers at the given time.

Responses

Request samples

Content type
application/json
{
  • "scheduled_at": "string",
  • "stops": [
    ],
  • "additional_information": "Two chairs and a table",
  • "name": "IDKEH",
  • "requested_capabilities": {
    },
  • "schedule_automatically_at": "2019-08-24T14:15:22Z"
}

Response samples

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

Undispatch tour's stops

Undispatch stops from a tour. Tour can be undispatched if it has undispatchable flag set to true.

If all of the stops that were dispatched into this tour from other bookings are undispatched, the tour will be cancelled.

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
stop_ids
required
Array of strings <uuid> (uuid)

IDs of the stops that will be undispatched.

Responses

Request samples

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

Response samples

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

Dispatch packages into a tour

This endpoint enables the dispatching of packages into tours for delivery from their current location to a hub or their destination.

You will need an existing tour to start adding packages to the route. A new one can be created using the Create Tour endpoint. If you want to deliver packages from or to a hub, you will then need to add a stop tied to a hub place using the Insert custom stop endpoint.

The pickup and dropoff stops can either be created for you or use existing stops on the tour. Please see the request samples for some usage examples.

The given packages must either be in created or at_hub status or already be planned on the same tour.

When using existing stops, these stops must be on this tour, must not have a parent (meaning they are not stops dispatched from a regular booking), and must be either in scheduled or approaching status.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Only permitted on tours when the packages extension is enabled and the tour is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
tour_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
Array of objects

List of packages to be added

required
Existing pickup stop (object) or Create pickup stop (object)

Schedule pickup of the package at an existing pickup stop or create a new pickup stop on the tour at the package's current location

required
Existing dropoff stop (object) or Create dropoff stop (object)

Schedule dropoff at an existing dropoff stop on the tour or create a new dropoff stop at the package's destination

Responses

Request samples

Content type
application/json
Example

Creates pickup stop at the current place of the package and a dropoff stop at the destination.

{
  • "packages": [
    ],
  • "pickup": {
    },
  • "dropoff": {
    }
}

Response samples

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

Remove packages from a tour

This endpoint allows to remove packages from a tour. In order to be eligible for the removal, the stops on the tour should have unresolved interactions for the referenced packages.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Only permitted on tours when the packages extension is enabled and the tour is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
tour_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
Array of objects

List of packages to be removed.

Responses

Request samples

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

Response samples

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

Insert custom stop into existing tour

Add a new, custom stop into an existing tour.

The stop can't be inserted before a stop that is not in either approaching or scheduled state.

The user must provide either the stop's coordinates or the the ID of a place. The referenced place must be visible to the user.

The actual newly created stop will be returned under the stop key in the response.

Permissions

Permitted for admins and org_managers when the booking or tour is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state, for customers when their booking is in to_be_dispatched state.

Not permitted for package tours.

User Roles

admin customer driver org_manager
βœ… βœ… β›” βœ…
Authorizations:
BearerAuth
path Parameters
tour_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
position
required
integer >= 1
required
object (NewCustomHailingBookingStop)

Responses

Request samples

Content type
application/json
{
  • "position": 3,
  • "stop": {
    }
}

Response samples

Content type
application/json
{
  • "stops": [
    ],
  • "stop": {
    }
}

Dispatch or move stops into existing tour

This endpoint allows dispatching of customer booking stops into existing tours as well as moving of dispatched stops between tours.

The given stops...

  • don't have to be from the same source booking or tour
  • will be inserted in the given order starting from the given position into the target tour
  • can only be inserted before a currently approaching or any scheduled stop when the target tour is already en_route, as parts of a route that were already done can no longer be modified

Dispatching of one or multiple eligible stops from customer bookings into an existing tour

Allows the dispatching of one or multiple customer booking stops into an existing tour. If you don't have a tour yet, use the Dispatch stops into tour endpoint instead.

For this, the source booking must be in to_be_dispatched or partially_dispatched states, and the stops themselves must be in scheduled, approaching, or failed states.

The target tour must be in one of the following states:

  • scheduled
  • to_be_dispatched
  • claimed
  • pickable
  • searching_provider
  • pending_provider
  • en_route

Moving of already dispatched stops between tours

Stops on tours can be moved into another tour. The stop(s) must be in either scheduled or approaching state, while the target and all stop source tours must be in one of the following states:

  • scheduled
  • to_be_dispatched
  • claimed
  • pickable
  • searching_provider
  • pending_provider
  • en_route

This applies both to custom stops on a tour as well as dispatched stops from a parent customer booking. In both cases, the stops from the source tours are fully moved over to the target tour.

Any source tour that...

  • becomes empty afterwards and isn't en_route yet will automatically be cancelled
  • is already en_route but no longer has any stops to complete will be automatically completed

Moving of dropoff stops between package dropoff tours

The dropoff stops of package dropoff tours can be moved between each other using this endpoint as well. This is only possible when both the source and destinantion package tours are in to_be_dispatched state. It also requires the pickup hub of each involved dropoff tour to be the same.

Any source package dropoff tour that becomes empty after this operation will be automatically cancelled.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Permitted when the tour is a regular tour in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state, or for a package dropoff tour in to_be_dispatched state.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
tour_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
position
required
integer >= 1
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "position": 3,
  • "stops": [
    ]
}

Response samples

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

Order stops of a given tour

Update the order of tour's stops. The stops must be either in approaching or scheduled state. The target tour must be in one of the following states:

  • scheduled
  • to_be_dispatched
  • claimed
  • pickable
  • searching_provider
  • pending_provider
  • en_route

Also note that it's not possible to move the last stop of package dropoff tours that are marked as return_to_hub.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Permitted for admins and org. managers when the tour/booking is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route. For drivers it's permitted only if it's en_route and the driver is the one working on it. For customers it's permitted only while the booking is in to_be_dispatched state.

User Roles

admin customer driver org_manager
βœ… βœ… βœ… βœ…
Authorizations:
BearerAuth
path Parameters
tour_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
Array of objects non-empty

Responses

Request samples

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

Response samples

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

Remove stops from a tour

Remove approaching or scheduled stops from a tour.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Only permitted when the tour is a regular tour in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
tour_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
Array of objects non-empty

Responses

Request samples

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

Response samples

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

Deduplicate stops of a tour

Deduplicate scheduled stops of a tour. The stops will be deduplicated based on their type and the destination or the place they have attached.

When removing duplicate stops with package interactions, the interactions will be moved into a single stop.

Dispatched stops that have parents are restricted from being deduplicated and will be kept as they are.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Permitted when the tour is a regular tour in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state, or for a package dropoff tour in to_be_dispatched state.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
tour_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
{
  • "stops": [
    ]
}

Fetch Bookings

Endpoints for fetching specific subsets of bookings

All Bookings

List all bookings

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

view
string
Default: "standard"
Enum: "standard" "compact"

Selects the display mode. When in doubt prefer the compact view to keep load on the backend as minimal as possible.

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

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Enum: "created_at" "local_scheduled_at" "scheduled_at"

Allows to request what property to sort the results by

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": {
    }
}

Fetch estimated arrival times for multiple bookings at once

Returns the estimated arrival time for each stop of the given bookings.

Whenever the ETAs are recalculated we send a Webhook/Websocket, please see hailing_booking.etas_recalculated for details.

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
ids
required
Array of strings <uuid> (Booking ID)

Responses

Request samples

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

Response samples

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

Export Bookings

Exports matching bookings as CSV.

Booking query filters may be applied.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
query Parameters
direction
string
Default: "desc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Enum: "created_at" "local_scheduled_at" "scheduled_at"

Allows to request what property to sort the results by

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"
}

Active bookings

List all active bookings, sorted by scheduled_at timestamp.

This endpoint is only available for customers and drivers.

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
direction
string
Default: "desc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Value: "scheduled_at"

Allows to request what property to sort the results by

view
string
Default: "standard"
Enum: "standard" "compact"

Selects the display mode. When in doubt prefer the compact view to keep load on the backend as minimal as possible.

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": {
    }
}

Delivered bookings

List all delivered bookings, sorted by scheduled_at timestamp.

This endpoint is only available for customers and drivers.

Delivered bookings have reached their destination and are no longer active, but might not yet be paid.

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
direction
string
Default: "desc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Value: "scheduled_at"

Allows to request what property to sort the results by

view
string
Default: "standard"
Enum: "standard" "compact"

Selects the display mode. When in doubt prefer the compact view to keep load on the backend as minimal as possible.

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": {
    }
}

Cancelled bookings

List all cancelled bookings, sorted by scheduled_at timestamp.

This endpoint is only available for customers and drivers.

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
direction
string
Default: "desc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Value: "scheduled_at"

Allows to request what property to sort the results by

view
string
Default: "standard"
Enum: "standard" "compact"

Selects the display mode. When in doubt prefer the compact view to keep load on the backend as minimal as possible.

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": {
    }
}

Scheduled bookings

List all scheduled bookings, sorted by scheduled_at timestamp.

For the drivers, this endpoint will return only the bookings that are claimed by the driver and not yet started.

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
direction
string
Default: "desc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Value: "scheduled_at"

Allows to request what property to sort the results by

view
string
Default: "standard"
Enum: "standard" "compact"

Selects the display mode. When in doubt prefer the compact view to keep load on the backend as minimal as possible.

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": {
    }
}

Fetch estimated arrival times for stops

Returns the estimated expected arrival time for each stop of the given booking

Whenever the ETAs are recalculated we send a Webhook/Websocket, please see hailing_booking.etas_recalculated for details.

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
{
  • "route_estimates": {
    }
}

Show Booking

Fetch a specific booking and its data.

Permissions

For drivers, only permitted if they are the assigned or a pending / preferred driver on the booking, for customers only on their own bookings.

User Roles

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

UUID identifier of the resource

query Parameters
view
string
Default: "standard"
Enum: "standard" "compact"

Selects the display mode. When in doubt prefer the compact view to keep load on the backend as minimal as possible.

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
{
  • "booking": {
    }
}

Track stop

Publicly accessible endpoint for tracking a stop via tracking code.

Authorizations:
BearerAuth
path Parameters
tracking_code
required
string or null (hailing_booking_stop_tracking_code)
Example: 1122334455

Unique, 10-digit, human-readable identifier used for tracking this stop.

On dispatched stops on a tour, the tracking code of the original regular customer booking stop (the parent) will be returned here.

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.

Responses

Response samples

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

Unassigned Bookings

Endpoints for listing claimable scheduled bookings as a driver

List of unassigned bookings

List all unassigned bookings, sorted by scheduled_at timestamp. The list will also include all the bookings where the driver is set as preferred.

This endpoint is only available for drivers, no matter if they are online or offline.

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
direction
string
Default: "asc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Value: "scheduled_at"

Allows to request what property to sort the results by

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 unassigned booking

Show unassigned booking.

This endpoint is only available for drivers, no matter if they are online or offline.

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
{
  • "booking": {
    }
}

Claim unassigned booking

This endpoint allows drivers to claim the booking for themselves.

This endpoint is only available for drivers, no matter if they are online or offline.

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
{
  • "booking": {
    }
}

Pickable Bookings

Pickable bookings can be enabled per service. If enabled, instant bookings do not go into driver matching but rather elegible drivers can pick them from a list of bookings that don't have a driver yet.

List pickable bookings

List all available pickable bookings for the requesting driver.

The result order is globally configurable per tenant, defaulting to ascending by scheduled_at, but it's also possible to change the default order to descending or the field to sort by to distance_from_first_stop via a request to the MotionTools customer success team. Introspection of the configuration is available via Driver Configuration endpoint, under pickable_bookings key.

In case that default ordering is set to distance_from_first_stop but the driver lacks the location, the ordering will default to using scheduled_at property of the booking.

Permissions

Only permitted when

  • Pickable bookings are enabled on a service
  • The driver is online
  • The driver is not on an active booking

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
direction
string
Default: "asc"
Enum: "asc" "desc"

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "scheduled_at"
Enum: "distance_from_first_stop" "scheduled_at"

Allows to request what property to sort the results by

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 pickable booking

Show a specific pickable booking

This endpoint is only available for online drivers.

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
{
  • "booking": {
    }
}

Pick a booking

Pick a specific pickable booking. Picking a booking will start the booking for the user.

This endpoint is only available for online drivers.

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
{
  • "booking": {
    }
}

Capabilities

These endpoints allow admins to configure capabilities to the needs of their business.

πŸ“˜ You can learn more about capabilities on our Help Center

πŸ”“ Permissions to access these endpoints can be detected using the permissions endpoint. The endpoints for capability values use the same permissions as for their capabilities, so no further separate permissions are indicated for those.

πŸ’‘ For API usage convenience the adminstrative endpoints use the capability and capability value keys as the identifiers in the HTTP routes, respectively.

List Capabilities

Returns a paginated list of capabilities configured by the admin's tenant.

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 Capability

Creates a new capability

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 (AdminCapabilityCreateRequest)

Responses

Request samples

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

Response samples

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

Show Capability

Returns an existing capability.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
capability_key
required
string (capability-key) ^[a-z][a-z_]{0,39}$
Example: vehicle_size

An immutable identifier for this capability that is to be used in API communication.

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
{
  • "capability": {
    }
}

Update Capability

Updates an existing capability.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
capability_key
required
string (capability-key) ^[a-z][a-z_]{0,39}$
Example: vehicle_size

An immutable identifier for this capability that is to be used in API communication.

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 (AdminCapabilityUpdateRequest)

Responses

Request samples

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

Response samples

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

List Capability Values

Returns a paginated list of capability values configured by the admin's tenant.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
capability_key
required
string (capability-key) ^[a-z][a-z_]{0,39}$
Example: vehicle_size

An immutable identifier for this capability that is to be used in API communication.

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
{}

Create Capability Value

Creates a new value for a capability

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
capability_key
required
string (capability-key) ^[a-z][a-z_]{0,39}$
Example: vehicle_size

An immutable identifier for this capability that is to be used in API communication.

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 (AdminCapabilityValueCreateRequest)

Responses

Request samples

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

Response samples

Content type
application/json
{}

Show Capability Value

Returns an existing capability value

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
capability_key
required
string (capability-key) ^[a-z][a-z_]{0,39}$
Example: vehicle_size

An immutable identifier for this capability that is to be used in API communication.

key
required
string (capability_value-key) ^[a-z\d][a-z_\d]{0,39}$
Example: large_van

An immutable identifier for this capability value that is to be used in API communication.

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
{}

Update Capability Value

Updates an existing capability value.

Permissions

Permissions to access this endpoint.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
capability_key
required
string (capability-key) ^[a-z][a-z_]{0,39}$
Example: vehicle_size

An immutable identifier for this capability that is to be used in API communication.

key
required
string (capability_value-key) ^[a-z\d][a-z_\d]{0,39}$
Example: large_van

An immutable identifier for this capability value that is to be used in API communication.

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 (AdminCapabilityValueUpdateRequest)

Responses

Request samples

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

Response samples

Content type
application/json
{}

Services

Endpoints to configure Services.

List Services

Returns a paginated list of Services owned by the admin's tenant.

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 a service

Creates a new service for the admin's tenant.

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 (CreateHailingServicePayload)

Responses

Request samples

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

Response samples

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

Show a service

Returns an existing service owned by admin's tenant.

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
{
  • "service": {
    }
}

Update a service

Updates an existing service owned by admin's tenant.

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 (UpdateHailingServicePayload)

Responses

Request samples

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

Response samples

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

Show proof configuration

Returns the current stop proofs configuration for the requested service ID and stop type.

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

type
required
string (hailing_booking_stop_type)
Enum: "pickup" "dropoff"

Stop type

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
{
  • "configuration": {
    }
}

Update proof configuration

Updates the stop proofs configuration for the given service ID and stop type.

Please note that advanced proofs configuration is not available on all plans, so availablity of certain options can be limited. Please reach out to our customer success team if you are interested in features not currently included in your plan.

Availablity of all features is indicated by the granular_proof_configuration flag being true on the Show proof configuration endpoint.

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

type
required
string (hailing_booking_stop_type)
Enum: "pickup" "dropoff"

Stop type

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 (AdminHailingServiceProofConfigurationUpdateRequest)

Responses

Request samples

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

Response samples

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

Stripe

Endpoints that aid in using Stripe's payment features and SDKs.

When working with Stripe, there's a range of credit cards and payment methods provided by them in order to test a specific outcome of payment processing. Test card numbers are usually used for input via UI, while payment methods are what most of the listed endpoints here expect. Stripe also provides cards and payment methods to test 3D Secure authentication and setup.

There are also credit card numbers for declined payments, as well as payment methods.

List Credit Cards

Lists all credit cards attached to the current user's Stripe customer 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
{
  • "cards": [
    ]
}

Create Pre-authorization

This API allows to create a credit-card pre-authorized Stripe Payment Intent, meaning a pre-defined amount of money will actually get blocked for later collection.

The returned client secret should be used with the Stripe SDK on the client side in case a SCA 3D secure flow needs to be confirmed.

Once completed, the payment intent should be in the status requires_capture and can be used for creating a booking.

When creating a pre-authorization for a booking, two things should be taken into consideration:

  1. The amount must match the discounted_amount of the booking plus the amount of the security_deposit component. There are two exceptions to this:
    1. When the discounted_amount is 0, in which case the given amount must be 100
    2. When the booking is already completed and in the stripe_failed state. Then the amount should be just the discounted_amount.
  2. The currency must match the booking's price currency.

Also note that the given payment method must be attached to the customer's Stripe account.

Unused payment intents are automatically canceled and the pre-authorization is removed if not used for a booking within 5 minutes of creation.

Permissions

Available when tenant has stripe payments 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

Responses

Request samples

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

Response samples

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

Booking's Payments

If one of the payment methods (e.g. cash, ec, credit_card) is used when creating the booking, the booking will enter the payment flow once it's state transitions to done. At this point the booking's payment state machine will kick in and the driver, the admin or the system will have to guide it through in order for the payment processing to be resolved.

Feature detection

You can detect which payment-related features are enabled for the tenant using the metadata fields describing available actions, payment methods and so on:

  • Use the Bookings Configuration endpoint, providing both the location and the customer's ID (if queried as admin), in order to fetch supported_vat_rates and supported_payment_methods which will later be used when creating a booking
  • Use available_payment_transitions field on the booking to drive the payment state machine
  • Use permitted_payment_actions field on the booking to enable or disable changing the price and payment method for the driver

Update the booking's price

Update the booking's price by providing a new final gross amount. This operation is only allowed for not-cancelled and unfinished booking's. Alternatively, you can also inspect permitted_payment_actions.change_price on the booking's standard view for the permission of this action.

The new price will be then used as a base price for all of the later price calculations (i.e. calculating the distance surcharge). Bear in mind that the previously applied voucher on the booking will also be applied to the new price.

Please note that if you trigger price recalculation after having set a custom price (for example by updating the route of a booking) you will need to again set a custom price as the newly calculated price will override your custom one.

Permissions

Available only for bookings that aren't done or cancelled and only for tenants with payments enabled.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
booking_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 (custom_price)

Admins can change the base price of the booking, by providing an amount here.

Responses

Request samples

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

Response samples

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

Perform a payment transition for a booking

Perform a payment transition for a booking to progress its payment flow.

State machine graph for the booking's payment state

Permissions

For drivers, only permitted if they are the assigned or a pending / preferred driver on the booking, for customers only on their own bookings.

Only possible when the booking is in processing_payment status.

The actual availability of transitions depends on the current state of the payment, available payment transitions for the user are indicated on the booking response inside the available_payment_transitions property.

User Roles

admin customer driver org_manager
βœ… β›” β›” βœ…
Authorizations:
BearerAuth
path Parameters
booking_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
{
  • "event": {
    }
}

Response samples

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

Discounts

Endpoints for configuring permanent discounts for customers.

List All Discounts

Lists all discounts for the user. Discounts will be listed per service area. For hailing_service discount type, the discounts will be also listed per service per service area.

If a discount is not persisted, it will have discount_percentage as null.

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
{
  • "discounts": [
    ]
}

Set a Discount

Set a discount for a customer.

Discounts can have multiple types. Depending off the type, different params are required.

This endpoint has upsert-like behaviour - if the given record does not yet exist, it will be created accordingly. If it exists it will be updated. To remove the discount pass null or 0 as a discount_percentage.

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
Service Discount (object) or Package Discount (object)

Responses

Request samples

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

Response samples

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

Driver's Capabilities

Endpoints that allow drivers to report their current capabilities.

Tenant's capabilities can be fetch at Query capabilities endpoint.

Current Capabilities

This endpoint returns the current capabilities set for the driver account. Lack of capabilities implies that the driver is "offline".

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
{
  • "capabilities": {
    }
}

Driver's Location

Endpoints that allow driver's location manipulation.

Set Location

This endpoint allows to set the current GPS location of the driver.

This endpoint will not update the location unless the configured time has passed or there was a sufficient change in the distance between old and new location. These values can be fetched via Hailing Driver Config. Changes of these values are published via websocket as well.

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

New location coordinates for the driver.

Responses

Request samples

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

Response samples

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

Driver's Status

Endpoints that can be used for changing driver's online/offline status.

When the driver is online, he is available for getting new booking requests. Offline driver will not get any new request and won't be considered for matching.

Go Online

Set current capabilities and location for the driver and make them available for booking requests.

Permissions

Allowed when user is currently offline

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 (driver_capabilities)

Driver's capabilities. Note that these can also be null.

required
object

Coordinates of the driver's current location.

Responses

Request samples

Content type
application/json
{
  • "capabilities": {
    },
  • "location": {
    }
}

Response samples

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

Go offline

Remove the driver's location and make them unavailable for new non-scheduled booking requests.

This endpoint doesn't remove the capabilities that were set for this driver.

Permissions

Allowed when user is currently online

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
{
  • "success": true
}

Send Driver offline

Set Driver User online status to offline as an admin or org. manager..

Permissions

Available when performed on driver users only

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
}

Fleet Configuration

Endpoints for introspecting fleet configuration for the tenant.

Fleet Configuration

Using this endpoint clients like our web dashboard can dynamically pull required information for all things related to fleet configuration at runtime to avoid having to manually configure and deploy new versions or launching new deployments.

This endpoint can be used with or without authentication. Unauthenticated use qualifies as guest-mode.

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
{
  • "fleet": {
    }
}

Vehicle Management

Endpoints for managing vehicles.

List all vehicles

Fetch all available vehicles. Note: This endpoint has a different response based on the user's role.

Permissions

Permitted only when fleet management feature is enabled.

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
object

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

order_by
string
Default: "booking_status"
Value: "booking_status"

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": {
    }
}

Create new vehicle

Create a new vehicle.

Permissions

Permitted only when fleet management 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

Responses

Request samples

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

Response samples

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

Show a vehicle

Show a vehicle with a given ID or SKU. Note: This endpoint has a different response based on the user's role.

Authorizations:
BearerAuth
path Parameters
required
uuid (string) or SKU (string)
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
{
  • "vehicle": {
    }
}

Update vehicle

Update existing vehicle's properties.

This actions is available when the vehicle is offline and it's not archived, and only for admins or org. managers.

Authorizations:
BearerAuth
path Parameters
required
uuid (string) or SKU (string)
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
{
  • "vehicle": {
    }
}

Response samples

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

Archive vehicle

Archive existing offline vehicle. This endpoint is only available to admins and org. managers.

NOTE: Trying to archive vehicles with operational status different from offline is not allowed. Please be aware that archiving the vehicle will nullify existing values for sku and module_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
{
  • "success": true
}

Change vehicle's operational status

Changes operational status on vehicle. Depending on the operational status, vehicle will be accessible to the users and will also define set of operations possible to do at the moment.

NOTE: Trying to change vehicle's status to offline when vehicle has active bookings is not permitted.

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
{
  • "vehicle": {
    }
}

Response samples

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

Refresh vehicle's status

Manually refresh Telematics Unit information for a particular vehicle.

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
{
  • "vehicle": {
    }
}

Vehicle Interaction

Endpoints for interacting with specific vehicles via their respective telematics providers.

Lock Engine

Locks the engine or immobilizer of the vehicle.

Availability depends on the telematics and vehicle type and can be inferred from supported_commands shown on vehicle.

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
{
  • "error_code": "unknown_tenant",
  • "description": "An english plain text description of the problem"
}

Unlock Engine

Unlocks the engine or immobilizer of the vehicle.

Availability depends on the telematics and vehicle type and can be inferred from supported_commands shown on vehicle.

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
{
  • "error_code": "unknown_tenant",
  • "description": "An english plain text description of the problem"
}

Lock Doors

Locks the door(s) of the vehicle.

Availability depends on the telematics and vehicle type and can be inferred from supported_commands shown on vehicle.

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
{
  • "error_code": "unknown_tenant",
  • "description": "An english plain text description of the problem"
}

Unlock Doors

Unlocks the door(s) of the vehicle.

Availability depends on the telematics and vehicle type and can be inferred from supported_commands shown on vehicle.

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
{
  • "error_code": "unknown_tenant",
  • "description": "An english plain text description of the problem"
}

Unlock Maintenance Compartment

Unlocks the maintenance (i.e. battery compartment) of the vehicle. Only can be performed when vehicle is in offline or in maintenance operational states.

Availability depends on the telematics and vehicle type and can be inferred from supported_commands shown on vehicle.

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
{
  • "error_code": "unknown_tenant",
  • "description": "An english plain text description of the problem"
}

Lock a Vehicle

Lock vehicle's door and engine, only available to drivers if enabled for tenant.

Before calling this endpoint, you should check for can_lock_vehicles flag inside driver config.

Permissions

Permitted only when fleet management feature is enabled.

Only allowed on vehicles that are not archived and only if the corresponding feature "Hailing Drivers can lock vehicles" 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
By ID (object) or By SKU (object) (vehicle_id_or_sku)

Vehicle query by ID or SKU

Responses

Request samples

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

Response samples

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

Unlock a Vehicle

Unlock vehicle's door and engine, only available to drivers if enabled for tenant.

Before calling this endpoint, you should check for can_lock_vehicles flag inside driver config.

Permissions

Permitted only when fleet management feature is enabled.

Only allowed on vehicles that are not archived and only if the corresponding feature "Hailing Drivers can lock vehicles" 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
By ID (object) or By SKU (object) (vehicle_id_or_sku)

Vehicle query by ID or SKU

Responses

Request samples

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

Response samples

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

Unlock a Vehicle Deprecated

Unlock vehicle's door and engine as driver.

Please consider using DELETE /api/vehicles/lock as this endpoint is deprecated.

Permissions

Permitted only when fleet management feature is enabled.

Only allowed on vehicles that are not archived and only if the corresponding feature "Hailing Drivers can lock vehicles" 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
By ID (object) or By SKU (object) (vehicle_id_or_sku)

Vehicle query by ID or SKU

Responses

Request samples

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

Response samples

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

Fetch Bluetooth credentials

Endpoint for fetching credentials for interacting with Bluetooth lock of a vehicle.

This endpoint is only available for vehicles that support Bluetooth (ie. bluetooth flag is set to true). For vehicles that don't support Bluetooth the endpoint will respond with 404 response.

The endpoint is only available to drivers.

Authorizations:
BearerAuth
path Parameters
required
uuid (string) or SKU (string)
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
{
  • "provider": "axa",
  • "bluetooth_module": "comodule",
  • "bluetooth_credentials": {
    }
}

Service Areas

Service Area Configuration

This endpoint allows to detect available configuration for the management of service areas.

It lists available values for payment methods, currencies and timezones that can be chosen when editing or creating service areas as an admin.

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
{
  • "config": {
    }
}

Change Service Area's metadata

Set or change service area's metadata, replacing any existing metadata on the service area.

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
{
  • "service_area": {
    }
}

Response samples

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

Partially Change Service Area's Metadata

Update the given service area'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
{
  • "service_area": {
    }
}

Response samples

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

Places

List all places

Returns a list of all places visible to the 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
object

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

order_by
string
Default: "name"
Value: "name"

Allows to request what property to sort the results by

direction
string
Default: "asc"
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": {
    }
}

Create a new place

Create a new place.

Always required fields for place creation are name, lat and lng. But in the case that tenant is configured to require stop contact details on any type of stops (stop_contact_details from bookings config endpoint has required set to true), then first_name, last_name, phone_number and email are required fields as well.

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 (Place)

An object representing a place. Depending on the tenant's config for stop contact details, this object can include contact details fields (first and last name, email and phone number).

Responses

Request samples

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

Response samples

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

Show a place

Responds with referenced place.

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
{
  • "place": {
    }
}

Update a place

Update the given place.

Note that only a subset of fields are allowed to be updated on a place.

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
{
  • "place": {
    }
}

Response samples

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

Archive a place

Archive referenced place.

In case a place is attached to a Shopify connection, it can't be archived and 422 error code will be returned.

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
{
  • "success": true
}

Change Place's metadata

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

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
{
  • "place": {
    }
}

Response samples

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

Partially Change Place's Metadata

Update the given place'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
{
  • "place": {
    }
}

Response samples

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

Fork a place

Updating the data of a place in-place is problematic because any changes to a place's location or other data can lead to confusion regarding already existing booking stops or packages that have been created based on this place - for example, a different service area and therefore price might now apply, a driver might already be underway to the old location and so on.

For this reason, we do not allow updating any address-related data of a place, but rather offer this endpoint.

Forking a place will:

  • Create a new place based off the original place's data (including metadata) combined with any (optional) custom values given as part of the request body
  • Archive the original place

Please note that for API usage convenience, any field not explicitly defined in your request will be inherited, so if you want to actually empty an optional value you should explicitly send this attribute with a null value in your request, otherwise the current value of the attribute would be inherited from the forked place.

Generally, this operation is only recommended for modifying data of a known location for example if more details about finding the entrance became available - for completely separate locations we recommend to instead create an entirely new place and use that.

Note that archiving of a place may be prohibited in the same ways as on the archiving endpoint, for example if a place is assigned to a customer's shopify connection. Please review the 422 error responses on this endpoint for possible restrictions.

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 (fork_place)

An object representing a place. Depending on the tenant's config for stop contact details, this object can include contact details fields (first and last name, email and phone number).

Responses

Request samples

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

Response samples

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

Zones

List all zones

Returns a list of all zones for this tenant. For customers only zones marked as visible that are not archived will be returned.

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
object

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

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

Allows to request sorting direction ascending or descending

order_by
string
Default: "name"
Value: "name"

Allows to request what property to sort the results by

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 new zone

An endpoint for creating a new zone by providing its name, color, shape and whether it's visible to the customer or not.

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
{
  • "zone": {
    }
}

Response samples

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

Show a Zone

Fetch a zone for a given ID. Note that full zone, with shape's GeoJson, will be returned on this endpoint.

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
{
  • "zone": {
    }
}

Update a Zone

Updates a zone for a given ID.

Passing archived set to true on this endpoint will result in archiving the zone.

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
{
  • "zone": {
    }
}

Response samples

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

Change Zone's Metadata

Set or change zone's metadata, replacing any existing metadata on the zone.

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
{
  • "zone": {
    }
}

Response samples

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

Partially Change Zone's Metadata

Update the given zone'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
{
  • "zone": {
    }
}

Response samples

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

Working Hours

Create working hours

Allows the creation of a working hours definition for resources that support them. Currently, this only applies to Places.

As an example, for a place that currently does not have working hours attached to it a request to create working hours with that place's id as workable_id and Place as workable_type must be sent to this endpoint. When hours are omitted, this will create a working hours configuration for this place that has never open.

The hours can afterwards be adjusted as needed using the working hours update endpoint. If working hours should no longer apply to this place, they can simply be deleted using the delete endpoint.

We will try to automatically detect the timezone if possible, for example by the service area the given place might be inside of. Otherwise, we will fall back to the default timezone of the tenant. A timezone can later on be edited using the update endpoint.

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 (WorkingHoursCreateRequest)

In order to create working hours for a resource like a place the corresponding correct workable_type and workable_id must be sent (i.e. Place and the id of that place).

Responses

Request samples

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

Response samples

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

Show working hours

Displays the stored data for the requested working hours resource.

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
{
  • "working_hours": {
    }
}

Update working hours

Existing working hours can be updated using this endpoint. This allows to define new working hours windows for each day of the week as well as removal and changing of the underlying timezone.

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 (WorkingHoursUpdateRequest)

Responses

Request samples

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

Response samples

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

Delete working hours

Removes the given working hours definitions, leaving the attached workable object without attached working hours again.

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
{
  • "success": true
}

Fetch open time window

Given a ISO8601 timestamp, returns the time window when the requested working hours are open for it.

The time window can eiter be an ongoing one, where the timestamp is between the opening and closing times, or it can be in the future, after the given timestamp because there are no currently open hours.

Time window can be null in case a time window couldn't be found.

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

UUID identifier of the resource

query Parameters
time
required
string
Example: time=2024-03-04T10:00:00+01:00

An ISO8601 timestamp for which the time window should be found.

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
{
  • "time_window": {
    }
}

Packages Overview

Packages are an extension to our bookings and tour building features that allow the dispatching and tracking of individual parcels from pickup to delivery

Similar to capabilities, packages can be configured with custom options for size, refrigeration and insurance via package properties. A price to be charged can then be configured for each of the available combinations.

A package is created by customers or on behalf of them by admins. The user has to choose a place where the package is to be picked up at, and a destination address. We generate shipping labels with scannable QR codes to be printed and attached to the packages.

Public tracking of each package is available via the web browser and API, and will reflect the current journey of the package.

Packages are dispatched into tours by admins, and will appear as individual items for drivers to scan or check in manually at their respective pickup or dropoff stops.

A package can travel via a tour from the pickup to the destination, from the pickup to a hub, from a hub to the destination, or from a hub to a hub.

In case a package cannot be picked up or delivered at the stop, it is possible to define standard failure reasons to be picked by the driver. A driver can also leave a custom note regarding the failure of the package.

We also offer the automated creation of optimized dropoff tours for packages from a hub, which will automatically create optimized routes that take into account the number of available drivers, individual shift lengths and used vehicles. The total weight of packages as well as the maximum capacity of a vehicle can also be considered optionally as part of this, to prevent the planning of overloaded tours.

Feature Detection

Endpoints for feature detection for packages.

Packages Configuration

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

The config is determined per-service area. The service area is figured out based on the pickup place's coordinates and/or destination lat, lng pair.

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.

Permissions

Available when packages feature is enabled

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
{
  • "packages": {
    }
}

List Package properties and their options

List all (enabled/disabled) properties (ordered) and their options (ordered) for the current tenant. It only permits users of tenants with Packages enabled.

Permissions

Available when packages 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

Responses

Response samples

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

Price Query

Allows to query the price for given pickup place, destination and requested package properties.

Prices are returned as integers and should be formatted accordingly. Only non-zero value for a component should be shown on the UI.

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 are properly resolved for the customer.

It's allowed to omit the requested_properties partially or entirely, in which case for each enabled property the smallest available value will be chosen automatically.

Permissions

Available when packages are enabled

User Roles

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

Query parameters required to pinpoint the specific price 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": {
    }
}

Package Management

Endpoints for listing and working with packages

List packages

Lists Hailing Packages.

Permissions

Permitted only when packages feature is enabled

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

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

Allows to request sorting direction ascending or descending

object

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

order_by
string
Default: "pickup_at"
Enum: "city" "local_pickup_at" "pickup_at"

Allows to request what property to sort the results by

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 a Package

Allows creation of package delivery requests.

Permissions

Permitted only when packages 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 (Create)

Responses

Request samples

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

Response samples

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

Generate Label Sheet

Allows requesting generation of a prepared A4 sheet of package labels in bulk, suitable for printing on adhesive paper.

The layout of the printout is determined by the passed layout parameter. Please refer to the parameter schema explained below for available options.

Note that the document generation is asynchronous, please follow the async document download documentation on how to get notified about the completion and how to fetch the final document once ready.

Permissions

Permitted only when packages 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
package_ids
required
Array of strings <uuid> (uuid)
variant
required
string (hailing_package_label_sheet_variant)
Enum: "1_label" "2_labels" "8_labels"

layout

Responses

Request samples

Content type
application/json
{
  • "package_ids": [
    ],
  • "variant": "1_label"
}

Response samples

Content type
application/json
{
  • "async_document_id": "fe8580cc-91d4-40c3-a3e1-a74d28bce41e",
  • "description": "string"
}

Show package

Show Hailing Package.

Permissions

Permitted only when packages feature is enabled

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
{
  • "package": {
    }
}

Show package journey

This endpoint returns all Interactions of a package in a chronological order (aka the journey).

Permissions

Permitted only when packages feature is enabled

User Roles

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

UUID identifier of the resource

query Parameters
version
string
Enum: "1" "2"

The response version which should be returned. The default is 1.

Version 1 journey only returns interaction-based events and force-delivery event which follows the interaction structure.

In version 2, the lookup events are included and the structure of force-delivery follows the structure of the journey event.

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
{
  • "journey": [
    ]
}

Track package

Publicly accessible endpoint for tracking the package via tracking code.

Authorizations:
BearerAuth
path Parameters
tracking_code
required
string (Package/Tracking-Code)
Example: 1122334455

Unique, 10-digit, human-readable identifier used for tracking the package.

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.

Responses

Response samples

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

Download PDF label

Via this endpoint a PDF label suitable for putting on the requested package can be downloaded.

If the package is delivered, the label will be automatically deleted and this endpoint will return 404.

Permissions

Permitted only when packages feature is enabled

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

Perform a transition on a package

Transitions referenced package using the given event.

For valid event name that should be given here, check available_transitions on List Packages or Show Package.

State machine graph for package's state
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
{
  • "event": {
    }
}

Response samples

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

Provide destination

When a package is created without a valid or geocodable destination and this is permitted by the can_create_packages_without_destination flag on the customer of the package, the package is created in the destination_needed status and cannot be put on tours.

Using this endpoint, the destination of such a package can be updated with the neccessary details. If GPS coordinates are not provided, we will again attempt to geocode against the provided destination address details.

Permissions

Permitted only when packages feature is enabled. Only possible to be performed when package is in destination_needed status.

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
{
  • "package": {
    }
}

Response samples

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

Recover failed package

Recover a package that is in failed state.

Whether package can be recovered or not is indicated via recoverable flag.

Permissions

Permitted only when packages feature is enabled. Only possible to be performed when package is in failed status.

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
object

Responses

Request samples

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

Response samples

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

Relocate a package

Relocate a package in created or at_hub state from a place to a hub.

Whether package can be relocated or not is indicated via relocatable flag.

Permissions

Permitted only when packages feature is enabled. Only possible to be performed when package is in created or at_hub state.

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
object

Responses

Request samples

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

Response samples

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

Change Package's metadata

Set package's metadata, replacing any existing metadata on the package.

Permissions

Permitted only when packages feature is enabled

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
{
  • "package": {
    }
}

Response samples

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

Partially Change Package's Metadata

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

Permissions

Permitted only when packages feature is enabled

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
{
  • "package": {
    }
}

Response samples

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

Update outcome of a package interaction Deprecated

Update outcome of a package interaction. For valid outcomes see request body specs.

Only usable by driver when stop is in arrived state.

⚠ Deprecated in favor of the Complete stop endpoint

Permissions

Available when packages are enabled, the user is an active driver on the booking and the package is not in failed state.

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 (PackageInteractionOutcomeSubmission)

Responses

Request samples

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

Response samples

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

Lookup package by shortcode or external label

This endpoint allows users to fetch package information via its shortcode or an external label.

Permissions

Available when packages 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
Package/Shortcode (string) or Package/External-Label (string)

Responses

Request samples

Content type
application/json
{
  • "identifier": "WL7XWJ9"
}

Response samples

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

Package Dispatching

These endpoints allow to create tours for package deliveries

Dispatch packages into a tour

This endpoint enables the dispatching of packages into tours for delivery from their current location to a hub or their destination.

You will need an existing tour to start adding packages to the route. A new one can be created using the Create Tour endpoint. If you want to deliver packages from or to a hub, you will then need to add a stop tied to a hub place using the Insert custom stop endpoint.

The pickup and dropoff stops can either be created for you or use existing stops on the tour. Please see the request samples for some usage examples.

The given packages must either be in created or at_hub status or already be planned on the same tour.

When using existing stops, these stops must be on this tour, must not have a parent (meaning they are not stops dispatched from a regular booking), and must be either in scheduled or approaching status.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Only permitted on tours when the packages extension is enabled and the tour is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
tour_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
Array of objects

List of packages to be added

required
Existing pickup stop (object) or Create pickup stop (object)

Schedule pickup of the package at an existing pickup stop or create a new pickup stop on the tour at the package's current location

required
Existing dropoff stop (object) or Create dropoff stop (object)

Schedule dropoff at an existing dropoff stop on the tour or create a new dropoff stop at the package's destination

Responses

Request samples

Content type
application/json
Example

Creates pickup stop at the current place of the package and a dropoff stop at the destination.

{
  • "packages": [
    ],
  • "pickup": {
    },
  • "dropoff": {
    }
}

Response samples

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

Remove packages from a tour

This endpoint allows to remove packages from a tour. In order to be eligible for the removal, the stops on the tour should have unresolved interactions for the referenced packages.

Package route consistency will be evaluated as part of the modification, and will lead to a 422 response with information on the problem in the response body. This only applies if you are using the packages extension.

  • Packages can only be picked up at their pickup place or an active hub, and can only be delivered to active hubs or the package's destination.
  • Packages that are to be picked up somewhere must have a planned dropoff on the same tour

Permissions

Only permitted on tours when the packages extension is enabled and the tour is in scheduled, to_be_dispatched, claimed, pickable, searching_provider, pending_provider or en_route state.

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
tour_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
Array of objects

List of packages to be removed.

Responses

Request samples

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

Response samples

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

Create package pickup tour

This endpoint allows the creation of a new package pickup tour booking.

A package pickup tour consists of one or more stops at places where packages are ready for pickup by a driver and a destination stop at a hub of the tenant, where the packages are delivered.

Please also carefully consider the detailed explanations for the request parameters on the schema explanation, especially for the destination_id and the route.

Permissions

Available when packages 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: application/json
required
object

Responses

Request samples

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

Response samples

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

Create package dropoff tour

This endpoint allows the creation of a new package dropoff tour booking.

Dropoff tour consists of an origin hub where a driver needs to pickup the packages and a list of stops where the packages need to be dropped off.

Please also carefully consider the detailed explanations for the request parameters on the schema explanation, especially for the origin_id and the route.

Permissions

Available when packages 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: application/json
required
object

Responses

Request samples

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

Response samples

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

Automatically plan package dropoff tours

This endpoint performs automated creation of package dropoff tours for a specified hub asynchronously.

Based on the provided local pickup date or date range, the origin hub and the defined vehicles we will look up all eligible packages in the at_hub status and will create route-optimized package dropoff tours for them.

To facilitate this, you must provide the vehicles that tours should be planned against, as well as their maximum shift durations.

The requested capabilities for each vehicle are used to also determine their corresponding vehicle speed profile and weight capacity. When packages have their weight_grams defined the maximum capacity will then be taken into account as part of the optimization.

The requested capabilities must be valid for the default service's configuration.

If the current location of a package has working hours configured, these will be taken into account for the route optimization process.

Process

Due to the asynchronous nature of this request the response for this request only returns a job_id.

When the autoplan completes, the system emits the hailing_package.dropoff_tour_autoplan.completed event.

Once this event is emitted, you can request the actual planned tours via the fetch automatically planned tours endpoint.

Permissions

Available when packages 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: application/json
required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f"
}

Fetch result for an automatically planned package dropoff tours

This endpoint returns previously automatically created package dropoff tours for the provided job ID (see autplan endpoint).

Until the system emitted the hailing_package.dropoff_tour_autoplan.completed event, this endpoint returns a 404 response.

The result of the autoplanning can be requested up to 30 minutes after the event has been emitted.

Notice

It's possible that there are more packages to optimize than can be fit into the given vehicle constraints - in such a case, the excess packages will be returned as part of the unassigned_packages collection.

Permissions

Available when packages are enabled

User Roles

admin customer driver org_manager
βœ… β›” β›” β›”
Authorizations:
BearerAuth
path Parameters
job_id
string <uuid>

Id returned by autplan endpoint to identify the job.

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
{
  • "created_tours": [
    ],
  • "unassigned_packages": [
    ]
}

Custom Screens

Custom Screens allow tenants to embed custom data into customer and driver mobile apps. A custom screen can be configured either via the admin dashboard or via the API.

The actual UI for the custom screen is not served via MotionTools backend - it's driven via an external service (e.g. tenant's backend) residing at the configured url to which all the calls are proxied. The calls are issued as POST requests and optionally can have a JSON body that includes parameters key for building the screen.

Controlling which parameters are sent is done in two ways:

  1. Some components allow defining parameters as a key-value object on them. See component schemas on Sample Endpoint for more info whether the components supports parameters or not.
  2. Each screen has a top level previous_page_parameters key that acts the same way as parameters key on the component, i.e. it's passed in the body of the request under parameters key. The only difference is that these parameters are passed when the user clicks on the "Back" button in the app, so they are used for building the previous page.

When inside a subscreen (parameters are present) the previous page parameters should be given in order for the user to have an ability to exit the page. On the root page (identified by the absence of proxy endpoint request parameters) the back button will simply close the custom screen.

Custom Screen Data Endpoint

πŸ’‘ Please note that this does not describe an actual MotionTools endpoint, but rather serves as a reference how an endpoint for serving custom screen data has to be implemented on the tenant side.

An endpoint conforming to this API schema can be used for serving custom screen data for MotionTools mobile app users. The custom screen can be configured through the MotionTools web dashboard by admin users and mobile app users will then see this screen in their app navigation.

The requests to the tenant-provided backend endpoint are proxied through the MotionTools backend and get forwarded to the tenant endpoint, which is expected to conform to the endpoint schema described here.

This then allows MotionTools mobile screens to be driven fully from the tenant side without any adjustments on the MotionTools side.

If the response served by this endpoint does not conform to the expected JSON schema the mobile app will instead receive a 422 error and display an error.

To prevent unresponsive UI the maximum response time for this endpoint is 1 second - if this time is exceeded, an error will be shown to the user. This is just the hard limit though - slow responses here immediately affect user experience, so the response should be as fast as possible. If there are some complex computations going on under the hood, it is recommended to utilize caching or precalculate as needed.

The path of this particular operation can be freely chosen as it's configurable, we only define it here at the root because this is just an isolated OpenAPI schema describing the desired interface.

πŸ“° Schema Changelog

2023-02-01 - backend_url JWT parameter

In order to ease dynamic detection of what MotionTools environment the request is coming from and where to dispatch further API calls towards, our custom screen JWT now contains a custom parameter backend_url, i.e. https://api.motiontools.io

2022-01-03 - web_url component

This release added a new web_url component that will open the given URL in an embedded web browser view inside the mobile apps.

Since the web view URL is controlled by the tenant backend, it can contain authentication tokens like a JWT to enable authenticated access to the web view.

If a returned screen page contains exactly one web view, it will be opened by the mobile apps automatically.

2021-12-20 - list_item component and navigation between pages

This release added the list_item component which can optionally point to another proxied page, allowing to build navigation between multiple pages.

To allow custom back button behaviour, previous_page_parameters was also introduced.

2021-12-06 - Initial release

The initial release of the feature, containing a single non-interactable component labeled_box

header Parameters
Authorization
required
string
Example: Bearer <JWT>

JWT token that proves the requesting user's MotionTools User ID we're requesting on behalf of has been authenticated.

This token uses the ECDSA ES512 signature algorithm. The signature must be verified against the signature public key handed out by MotionTools when configuring the custom screen.

Fields included:

  • sub: The MotionTools user ID on whose behalf this request is being made
  • exp: A short expiration time for this token. Since tokens are generated per request this is very short-lived
  • jti: A unique ID for this JWT. It is recommended to check this against a token reuse store to prevent replay attacks.
  • backend_url: This is a custom field and indicates the MotionTools backend URL the request and JWT are originating from. This can be helpful when the endpoint targets different MotionTools environments as without further configuration the required API base url can be taken from this field.

If enabled on the custom screen configuration using the embed_profile_in_jwt flag, the following additional fields will be available in the JWT as per https://www.iana.org/assignments/jwt/jwt.xhtml. This can be useful if you want to add some personalization to your custom screen content without adding the need to make additional API calls and storing corresponding API keys alongside your custom screen endpoint:

  • name
  • given_name
  • family_name
  • email
  • email_verified
Accept-Language
required
string
Example: de,en;q=0.8

Accepted languages of the user we are requesting on behalf of. This is based off the tenant configuration on MotionTools and the user account, and uses ISO639-1 language codes. So assuming a tenant is configured to have default language en and available languages also include de, and fr, if the user we are requesting for has their language on MotionTools as de, we would send here de and en, with de being the preferred language and en the fallback.

All text rendered on screen must be localized based on this.

Responses

Response samples

Content type
application/json
{
  • "title": "Widgets",
  • "previous_page_parameters": {
    },
  • "components": [
    ]
}

Webhooks

You can make your integration listen to events that occur on the MotionTools platform by leveraging our Webhooks. Subscribing to webhooks is done via our Admin Dashboard, and has to be performed by an Admin.

This section describes all available webhook events and the data contained in them.

Webhooks enable powerful integration possibilities between MotionTools and any other system you might it to interact with in an efficient way.

Instead of having to query every few seconds a list of data like bookings and comparing for changes, your integration subscribes to the appropriate webhook and will be notified by us when a corresponding change has taken place.

A very common use case is for example the subscription to the hailing_booking.transition event to get notified about a booking being started, completed, cancelled and other events, for further processing in another system.

Request verification

To verify that an incoming webhook request was not maliciously forged or modified we include a signature as a part of the request headers. The signature must be validated on your side to ensure no fraudulent event notification has occured.

Ed25519 is used as an encryption algorithm, and the signature is given Base64-encoded in the X-Mtools-Signature request header.

Verification example in Ruby:

require "rbnacl"

message = webhook_request.body
signature = webhook_request.headers["X-Mtools-Signature"]
public_key_bytestr = Base64.decode64 public_key_base64

verify_key = RbNaCl::VerifyKey.new public_key_bytestr
verify_key.verify(signature, message)

For more detailed information see also the documentation.

driver.busy Webhook

Published when the driver becomes busy

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "busy"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "busy",
  • "data": {
    }
}

driver.locations_updated Webhook

Bulk event reporting the latest locations of a subset of online drivers for a certain organization, regardless of being on an active booking.

Due to maximum message sizes such messages don't neccessarily contain the locations for all online drivers of that organization.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "locations_updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "locations_updated",
  • "data": {
    }
}

driver.no_longer_busy Webhook

Published when the driver becomes idle

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "no_longer_busy"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "no_longer_busy",
  • "data": {
    }
}

driver.offline Webhook

Published when the driver goes offline

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "offline"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "offline",
  • "data": {
    }
}

driver.online Webhook

Published when the driver goes online

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "online"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "online",
  • "data": {
    }
}

driver.service_area_changed Webhook

Published when the driver's service area is changed, whether the driver is on a booking or not.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "service_area_changed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "service_area_changed",
  • "data": {
    }
}

driver_request.cancelled Webhook

Notifies about a no-longer available instant driver request for booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver_request"

Namespace of event resource

event
required
string
Value: "cancelled"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver_request",
  • "event": "cancelled",
  • "data": {
    }
}

driver_request.created Webhook

Notifies about a new instant driver request for booking for drivers

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver_request"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver_request",
  • "event": "created",
  • "data": {
    }
}

hailing_booking.active_status_changed Webhook

Notifies customer and driver about change of active status of a booking.

Note: When this event is triggered for a role driver, it can happen that there's no driver on the booking. This usually indicates that the booking became active for driver because a matching happened and there's now a pending driver. In that case affected_user_id will be the ID of this driver. Also note that this is true regardless of active being set to true or false.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "active_status_changed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "active_status_changed",
  • "data": {
    }
}

hailing_booking.created Webhook

Published when a new booking has been created

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "created",
  • "data": {
    }
}

hailing_booking.driver_location_updated Webhook

Published when a driver sent an updated GPS location that affects an ongoing booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "driver_location_updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "driver_location_updated",
  • "data": {
    }
}

hailing_booking.etas_recalculated Webhook

Published when the ETAs for the booking's stops have been recalculated, see EstimateBookingStopsArrivals endpoint.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "etas_recalculated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "etas_recalculated",
  • "data": {
    }
}

hailing_booking.force_assigned Webhook

Notifies about booking being forcefully assigned to a driver.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "force_assigned"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "force_assigned",
  • "data": {
    }
}

hailing_booking.force_unassigned Webhook

Notifies about booking being forcefully un-assigned from a driver.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "force_unassigned"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "force_unassigned",
  • "data": {
    }
}

hailing_booking.modified Webhook

Published when some part of booking is modified, e.g. when stops are changed. It's published for both bookings and tours.

For drivers it's only published while the booking is in en_route state.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
  • ServiceAreaDrivers: private-service-area-drivers=:tenant_id@:service_area_id Channel for broadcasts to drivers of a tenant in a specific service area
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "modified"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "modified",
  • "data": {
    }
}

hailing_booking.route_changed Webhook

Published when the route of a booking or tour has changed, i.e. by adding or removing stops, changing their locations, changing their order and so on.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "route_changed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "route_changed",
  • "data": {
    }
}

hailing_booking.transition Webhook

Indicates a change of status of a booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "transition"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "transition",
  • "data": {
    }
}

hailing_booking_stop.transition Webhook

Indicates a change of status for a specific stop of a booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking_stop"

Namespace of event resource

event
required
string
Value: "transition"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking_stop",
  • "event": "transition",
  • "data": {
    }
}

hailing_package.created Webhook

Published when a new package has been created

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package",
  • "event": "created",
  • "data": {
    }
}

hailing_package.dropoff_tour_autoplan.completed Webhook

Published when a Dropoff Tour Autoplan job has been completed, see autoplan endpoint for more details.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package.dropoff_tour_autoplan"

Namespace of event resource

event
required
string
Value: "completed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package.dropoff_tour_autoplan",
  • "event": "completed",
  • "data": {
    }
}

hailing_package.interaction_failed Webhook

Published when a package interaction is marked as failed.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package"

Namespace of event resource

event
required
string
Value: "interaction_failed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package",
  • "event": "interaction_failed",
  • "data": {
    }
}

hailing_package.label_prepared Webhook

After creation, the corresponding label for a package is created asynchronously in the background.

Therefore, download of a label as well as creation of a label sheet are not immediately possible.

This event can be utilized to get notified when a label has been prepared, so that download and label sheet generation become available.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package"

Namespace of event resource

event
required
string
Value: "label_prepared"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package",
  • "event": "label_prepared",
  • "data": {
    }
}

hailing_package.transition Webhook

Indicates a change of status for a package

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package"

Namespace of event resource

event
required
string
Value: "transition"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package",
  • "event": "transition",
  • "data": {
    }
}

service_area.created Webhook

Notifies about a new service area being created

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "service_area"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "service_area",
  • "event": "created",
  • "data": {
    }
}

service_area.updated Webhook

Notifies about a service area being updated

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "service_area"

Namespace of event resource

event
required
string
Value: "updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "service_area",
  • "event": "updated",
  • "data": {
    }
}

shopify.package_creation_failed Webhook

Notifies about failed package creation for Shopify orders.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "shopify"

Namespace of event resource

event
required
string
Value: "package_creation_failed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "shopify",
  • "event": "package_creation_failed",
  • "data": {
    }
}

user.anonymize Webhook

Published when a request for the user's anonymization is received. Note that the actual process of anonymization happens asynchronously."

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user"

Namespace of event resource

event
required
string
Value: "anonymize"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user",
  • "event": "anonymize",
  • "data": {
    }
}

user.created_by_admin Webhook

Notifies about a user being created by an admin. Currently only customers can be created by admins, all other roles are created using invitations instead.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user"

Namespace of event resource

event
required
string
Value: "created_by_admin"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user",
  • "event": "created_by_admin",
  • "data": {
    }
}

user.email_verification.verified Webhook

Published when the user verifies email.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user.email_verification"

Namespace of event resource

event
required
string
Value: "verified"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user.email_verification",
  • "event": "verified",
  • "data": {
    }
}

user.invited Webhook

Notifies about a new user being invited. Currently available for drivers, org_manager and admin roles.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user"

Namespace of event resource

event
required
string
Value: "invited"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user",
  • "event": "invited",
  • "data": {
    }
}

user.invoice_address.updated Webhook

Published when user's invoice address is updated, either by the user or by an admin.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user.invoice_address"

Namespace of event resource

event
required
string
Value: "updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user.invoice_address",
  • "event": "updated",
  • "data": {
    }
}

user.opt_ins.updated Webhook

Published when user updates the opt-ins.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user.opt_ins"

Namespace of event resource

event
required
string
Value: "updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user.opt_ins",
  • "event": "updated",
  • "data": {
    }
}

user.profile_details.updated Webhook

Published when user's profile details are updated, either by the user or by an admin.

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user.profile_details"

Namespace of event resource

event
required
string
Value: "updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user.profile_details",
  • "event": "updated",
  • "data": {
    }
}

user.signup Webhook

Notifies about a new user signup. This can be both from regular signup or from accepting an invitation by signing up using the invited e-mail address

Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user"

Namespace of event resource

event
required
string
Value: "signup"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user",
  • "event": "signup",
  • "data": {
    }
}

Websockets

We support realtime communications via Pusher Channels.

Configuration

To connect to websocket channel, you should setup your client using one of Pusher SDKs and connection configuration for our cluster. Note that you have to pass additional auth object with Authorization and X-Client-Version headers set to appropriate values, so that Pusher client can make authorized requests to our server.

JS example for staging with everything properly set would look something like this:

new Pusher(config.appKey, {
  cluster: config.cluster,
  forceTLS: true,
  authEndpoint: "https://api.motiontools-staging.io/api/channels/auth",
  auth: {
    headers: {
      Authorization: `Bearer ${currentUser.accessToken}`,
      "X-Client-Version": currentClient.version
    }
  }
})

Subscribing to channels

To start receiving from registered channel you have to create a new subscription on existing client by providing channel name. We don't support wildcards for channels but for every event, you can find which channels support it.

All the placeholders within channel key (like :user_id) have to be replaced with actual data. When the string representing channel name is build, you can subscribe to the channel like this:

pusher = new Pusher(...)
channel_id = "private-user=7a98a35c-531e-4a4d-abb6-e632d78ea01b"

channel = pusher.subscribe(channel_id)

For more information about event listeners, please check Pusher docs.

driver.busy Webhook

Published when the driver becomes busy

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "busy"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "busy",
  • "data": {
    }
}

driver.location_updated Webhook

Published when the driver's location is updated, regardless whether the driver is on a booking.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "location_updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "location_updated",
  • "data": {
    }
}

driver.locations_updated Webhook

Bulk event reporting the latest locations of a subset of online drivers for a certain organization, regardless of being on an active booking.

Due to maximum message sizes such messages don't neccessarily contain the locations for all online drivers of that organization.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "locations_updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "locations_updated",
  • "data": {
    }
}

driver.no_longer_busy Webhook

Published when the driver becomes idle

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "no_longer_busy"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "no_longer_busy",
  • "data": {
    }
}

driver.offline Webhook

Published when the driver goes offline

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "offline"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "offline",
  • "data": {
    }
}

driver.online Webhook

Published when the driver goes online

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "online"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "online",
  • "data": {
    }
}

driver.organization_changed Webhook

Published when the driver's organization is changed

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "organization_changed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "organization_changed",
  • "data": {
    }
}

driver.service_area_changed Webhook

Published when the driver's service area is changed, whether the driver is on a booking or not.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver"

Namespace of event resource

event
required
string
Value: "service_area_changed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver",
  • "event": "service_area_changed",
  • "data": {
    }
}

driver_config.updated Webhook

Published when the config has changed.

Publication channels:

  • ServiceAreaDrivers: private-service-area-drivers=:tenant_id@:service_area_id Channel for broadcasts to drivers of a tenant in a specific service area
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver_config"

Namespace of event resource

event
required
string
Value: "updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver_config",
  • "event": "updated",
  • "data": {
    }
}

driver_request.cancelled Webhook

Notifies about a no-longer available instant driver request for booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver_request"

Namespace of event resource

event
required
string
Value: "cancelled"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver_request",
  • "event": "cancelled",
  • "data": {
    }
}

driver_request.created Webhook

Notifies about a new instant driver request for booking for drivers

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "driver_request"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "driver_request",
  • "event": "created",
  • "data": {
    }
}

hailing_booking.active_status_changed Webhook

Notifies customer and driver about change of active status of a booking.

Note: When this event is triggered for a role driver, it can happen that there's no driver on the booking. This usually indicates that the booking became active for driver because a matching happened and there's now a pending driver. In that case affected_user_id will be the ID of this driver. Also note that this is true regardless of active being set to true or false.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "active_status_changed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "active_status_changed",
  • "data": {
    }
}

hailing_booking.approaching_stop_changed Webhook

Published when the approaching stop of an en route tour has been changed

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "approaching_stop_changed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "approaching_stop_changed",
  • "data": {
    }
}

hailing_booking.claimable Webhook

Indicates that a scheduled booking has become claimable by drivers.

This can be the case for newly created scheduled bookings, when a driver that previously claimed a booking unclaims it again, when an admin reassigns the booking or when a manually dispatched booking is scheduled

Publication channels:

  • ServiceAreaDrivers: private-service-area-drivers=:tenant_id@:service_area_id Channel for broadcasts to drivers of a tenant in a specific service area
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "claimable"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "claimable",
  • "data": {
    }
}

hailing_booking.claimed_ready_for_start Webhook

Indicates that a booking claimed by the driver is ready to be started.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "claimed_ready_for_start"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "claimed_ready_for_start",
  • "data": {
    }
}

hailing_booking.created Webhook

Published when a new booking has been created

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "created",
  • "data": {
    }
}

hailing_booking.driver_location_updated Webhook

Published when a driver sent an updated GPS location that affects an ongoing booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "driver_location_updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "driver_location_updated",
  • "data": {
    }
}

hailing_booking.etas_recalculated Webhook

Published when the ETAs for the booking's stops have been recalculated, see EstimateBookingStopsArrivals endpoint.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "etas_recalculated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "etas_recalculated",
  • "data": {
    }
}

hailing_booking.force_assigned Webhook

Notifies about booking being forcefully assigned to a driver.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "force_assigned"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "force_assigned",
  • "data": {
    }
}

hailing_booking.force_unassigned Webhook

Notifies about booking being forcefully un-assigned from a driver.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "force_unassigned"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "force_unassigned",
  • "data": {
    }
}

hailing_booking.modified Webhook

Published when some part of booking is modified, e.g. when stops are changed. It's published for both bookings and tours.

For drivers it's only published while the booking is in en_route state.

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
  • PrivateUser: private-user=:user_id Per user private channel
  • ServiceAreaDrivers: private-service-area-drivers=:tenant_id@:service_area_id Channel for broadcasts to drivers of a tenant in a specific service area
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "modified"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "modified",
  • "data": {
    }
}

hailing_booking.no_longer_claimable Webhook

Indicates that a scheduled booking is no longer available for claiming

Publication channels:

  • ServiceAreaDrivers: private-service-area-drivers=:tenant_id@:service_area_id Channel for broadcasts to drivers of a tenant in a specific service area
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "no_longer_claimable"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "no_longer_claimable",
  • "data": {
    }
}

hailing_booking.no_longer_pickable Webhook

Indicates that a booking is no longer pickable

Publication channels:

  • ServiceAreaDrivers: private-service-area-drivers=:tenant_id@:service_area_id Channel for broadcasts to drivers of a tenant in a specific service area
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "no_longer_pickable"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "no_longer_pickable",
  • "data": {
    }
}

hailing_booking.pickable Webhook

Indicates that a booking has become pickable by drivers.

A pickable booking is an instant booking that does not go via driver matching but rather can be picked from a list by elegible drivers. This feature can be enabled per service.

Publication channels:

  • ServiceAreaDrivers: private-service-area-drivers=:tenant_id@:service_area_id Channel for broadcasts to drivers of a tenant in a specific service area
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "pickable"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "pickable",
  • "data": {
    }
}

hailing_booking.transition Webhook

Indicates a change of status of a booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking"

Namespace of event resource

event
required
string
Value: "transition"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking",
  • "event": "transition",
  • "data": {
    }
}

hailing_booking_payment.transition Webhook

Notifies about change of booking payment status

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking_payment"

Namespace of event resource

event
required
string
Value: "transition"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking_payment",
  • "event": "transition",
  • "data": {
    }
}

hailing_booking_stop.transition Webhook

Indicates a change of status for a specific stop of a booking

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • OrganizationManager: private-organization-manager=:organization_id Channel for organization managers
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_booking_stop"

Namespace of event resource

event
required
string
Value: "transition"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_booking_stop",
  • "event": "transition",
  • "data": {
    }
}

hailing_package.created Webhook

Published when a new package has been created

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package",
  • "event": "created",
  • "data": {
    }
}

hailing_package.dropoff_tour_autoplan.completed Webhook

Published when a Dropoff Tour Autoplan job has been completed, see autoplan endpoint for more details.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package.dropoff_tour_autoplan"

Namespace of event resource

event
required
string
Value: "completed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package.dropoff_tour_autoplan",
  • "event": "completed",
  • "data": {
    }
}

hailing_package.label_prepared Webhook

After creation, the corresponding label for a package is created asynchronously in the background.

Therefore, download of a label as well as creation of a label sheet are not immediately possible.

This event can be utilized to get notified when a label has been prepared, so that download and label sheet generation become available.

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package"

Namespace of event resource

event
required
string
Value: "label_prepared"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package",
  • "event": "label_prepared",
  • "data": {
    }
}

hailing_package.transition Webhook

Indicates a change of status for a package

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "hailing_package"

Namespace of event resource

event
required
string
Value: "transition"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "hailing_package",
  • "event": "transition",
  • "data": {
    }
}

service_area.created Webhook

Notifies about a new service area being created

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "service_area"

Namespace of event resource

event
required
string
Value: "created"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "service_area",
  • "event": "created",
  • "data": {
    }
}

service_area.updated Webhook

Notifies about a service area being updated

Publication channels:

  • TenantAdmin: private-tenant-admin=:tenant_url_key Channel for admins of a certain tenant
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "service_area"

Namespace of event resource

event
required
string
Value: "updated"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "service_area",
  • "event": "updated",
  • "data": {
    }
}

user.async_document.completed Webhook

Published when an asynchronous document has been prepared and is ready for download

Publication channels:

  • PrivateUser: private-user=:user_id Per user private channel
Request Body schema: application/json
id
required
string <uuid>

ID of the event

timestamp
required
string <date-time>

DateTime object in ISO8601 format

resource_type
required
string
Value: "user.async_document"

Namespace of event resource

event
required
string
Value: "completed"

Name of the specific event

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "db76ba31-96f8-4c95-b71d-85ade5c7a640",
  • "timestamp": "2020-11-09T10:19:07Z",
  • "resource_type": "user.async_document",
  • "event": "completed",
  • "data": {
    }
}