MotionTools API documentation (1.0.0)

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.

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

• 🛒 Create a booking via API
• 👤 Invite users via API
• ⚡ Use Webhooks to build custom integrations

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

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

To name a few:

• User Accounts, Adding Users & Authentication
• Organizations
• Bookings, Drivers and Advanced Dispatching
• Vehicle Fleet
• Packages and Package Dispatching
• Custom Screens
• Service Areas
• Payments via Stripe

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

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.

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

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.

• 👉 See Create an API Key

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

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

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

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.

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

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:

• Users
• Bookings
• Stops
• Packages
• Organizations
• Service Areas
• Zones
• Places

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:

• Users
• Bookings
• Stops
• Packages
• Service Areas
• Zones
• Places

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:

• User accounts
• Bookings
• Packages
• Places

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.

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

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

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.

Endpoints for fetching configuration for a specific MotionTools tenant

Endpoints for uploading files for attaching against other resources.

Utilities endpoints that help facilitate other services

This section describes endpoints for user account signup & signin

Endpoints relating to authentication

Functionality for enabling users to reset their forgotten account passwords

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.

Endpoints related to the currently authenticated user account