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 π:
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.
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.
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.
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:
X-Client-Version
(see here) header must be ommited;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.
410 Gone
HTTP response code. Upon this response clients must show
a notification to the user to upgrade their app.400
HTTP response with the unknown_tenant
error code.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:
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:
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:
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:
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.
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.
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.
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.
Use the supported_payment_methods
list returned on the individual booking API response.
Returns the enabled customizations (and their values, where applicable) for the tenant.
The tenant is determined based on the X-Client-Version
header value.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "customizations": {
- "some_enum": "foo",
- "some_boolean": true,
- "some_multi_enum": [
- "one",
- "two"
]
}
}
Upload images or documents 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.
The response will also contain a type
property, which indicates what kind
of file type was detected - this determines to what the upload can subsequently
be attached, as for example only images are eligible for image-based attachments
like stop proof images and signatures, whereas only (pdf) documents can be
attached as documents.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "content_type": "image/jpeg",
- "filename": "example.jpg",
- "size": 0,
- "type": "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.
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.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{
}
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 routeall_pickups_before_all_dropoffs
will place pickups before any dropoff in the routeBe 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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "route_optimization": {
- "scheduled_at": "2019-08-24T14:15:22Z",
- "strategy": null,
- "custom_stops": [
- {
- "id": "stop_1",
- "lat": 53.551085,
- "lng": 10.3824,
- "service_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",
- "type": "pickup",
- "earliest_arrival_at": "2019-08-24T14:15:22Z",
- "latest_arrival_at": "2019-08-24T14:15:22Z"
}
], - "existing_stops": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
], - "start_id": "stop_1",
- "destination_id": "stop_2",
- "version": 3,
- "target": {
- "tour": true
}, - "ignore_time_windows": true
}
}
{- "route_optimization": {
- "scheduled_at": "2019-08-24T14:15:22Z",
- "total_duration_seconds": 240,
- "total_distance_meters": 8000,
- "total_waiting_time_seconds": 42,
- "unassigned_stops": [
- {
- "id": "string",
- "reason": "cannot be visited within time window"
}
], - "stops": [
- {
- "id": "string",
- "lat": 53.551085,
- "lng": 10.3824,
- "distance_meters": 0,
- "driving_time_seconds": 0,
- "arrival_time_seconds": 0,
- "waiting_time_seconds": 0,
- "duration_seconds": 0,
- "expected_arrival_at": "2019-08-24T14:15:22Z"
}
]
}
}
This endpoint estimates the time of arrival distance for each provided stop to the first stop.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "route_estimate": {
- "service_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",
- "stops": [
- {
- "id": "stop_1",
- "type": "pickup",
- "lat": 53.551085,
- "lng": 10.3824,
- "earliest_arrival_at": "2019-08-24T14:15:22Z",
- "latest_arrival_at": "2019-08-24T14:15:22Z"
}, - {
- "id": "stop_1",
- "type": "pickup",
- "lat": 53.551085,
- "lng": 10.3824,
- "earliest_arrival_at": "2019-08-24T14:15:22Z",
- "latest_arrival_at": "2019-08-24T14:15:22Z"
}
], - "scheduled_at": "2019-08-24T14:15:22Z"
}
}
{- "route_estimate": {
- "total_duration_seconds": 240,
- "total_distance_meters": 8000,
- "total_waiting_time_seconds": 42,
- "unassigned_stops": [
- {
- "id": "string",
- "reason": "cannot be visited within time window"
}
], - "stops": [
- {
- "id": "string",
- "lat": 53.551085,
- "lng": 10.3824,
- "distance_meters": 0,
- "driving_time_seconds": 0,
- "arrival_time_seconds": 0,
- "waiting_time_seconds": 0,
- "duration_seconds": 0,
- "expected_arrival_at": "2019-08-24T14:15:22Z"
}
], - "scheduled_at": "2019-08-24T14:15:22Z"
}
}
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
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "user": {
- "password": "pa$$word",
- "opt_ins": {
- "marketing": true,
- "tracking": true
}
}
}
{- "access_token": "string",
- "refresh_token": "string",
- "expires_in": 86400
}
Allows signin using known e-mail and password combination
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{
}
{- "access_token": "string",
- "refresh_token": "string",
- "expires_in": 86400
}
Acquire a new short-lived access token from long-lived refresh token
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
refresh_token required | string |
{- "refresh_token": "94245008a695791b5f7b20621e842c8542654d0f"
}
{- "access_token": "string",
- "expires_in": 86400
}
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.
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 |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "error_code": "unknown_tenant",
- "description": "An english plain text description of the problem"
}
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.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{
}
{- "success": true
}
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.
After the new password is set, the user will be logged out from all of their active sessions.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "user": {
- "token": "string",
- "password": "pa$$word"
}
}
{- "error_code": "unknown_tenant",
- "description": "An english plain text description of the problem"
}
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.
Allows to store a firebase push notifications token for this user, which will subsequently be used for delivering push notifications.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
token required | string The firebase push token value to be stored |
{- "token": "string"
}
{- "success": true
}
Remove a registered push notification token. The push token removed is the one tied to the current application session (identified by the access token).
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "success": true
}
Get details of currently signed in user account
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "role": "admin",
- "onboarding_complete": true,
- "status": "invited",
- "organization": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "My Cool Organization"
}, - "managed_organizations": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "My Cool Organization"
}
]
}
}
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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "flags": {
- "can_create_packages_without_destination": false,
- "can_create_packages_with_destination_outside_of_service_area": false
}
}
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.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "user": {
- "supported_payment_methods": [
- "credit_card",
- "cash",
- "ec",
- "invoice"
]
}
}
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.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "account_features": [
- {
- "completed": true,
- "skippable": true,
- "onboarding": true,
- "editable": true,
- "name": "profile_details",
- "attributes": [
- {
- "key": "first_name",
- "type": "string",
- "presence": "required"
}
]
}
]
}
Use this endpoint when email verification is required during onboarding process for particular user.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
verification_code required | string 4 digit code sent to verify email address |
{- "verification_code": "string"
}
{- "success": true
}
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"
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "success": true
}
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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
user_id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "flags": {
- "can_create_packages_without_destination": false,
- "can_create_packages_with_destination_outside_of_service_area": false
}
}
{- "flags": {
- "can_create_packages_without_destination": false,
- "can_create_packages_with_destination_outside_of_service_area": false
}
}
Allows to update a user's configuration flags.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
user_id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "flags": {
- "can_create_packages_without_destination": false,
- "can_create_packages_with_destination_outside_of_service_area": false
}
}
{- "flags": {
- "can_create_packages_without_destination": false,
- "can_create_packages_with_destination_outside_of_service_area": false
}
}
Returns current values set on the user's profile
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "profile": {
- "first_name": "string",
- "last_name": "string",
- "phone_number": "+49123123123",
- "birthday": "2019-08-24",
- "company_name": "ACME Inc."
}
}
Allows to update the current user's profile.
Partial updates (e.g. just first_name
) are not supported.
Permitted when the Profile Details feature is enabled.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object or null (UserProfile) User's profile details.
|
{- "profile": {
- "first_name": "string",
- "last_name": "string",
- "phone_number": "+49123123123",
- "birthday": "2019-08-24",
- "company_name": "ACME Inc."
}
}
{- "profile": {
- "first_name": "string",
- "last_name": "string",
- "phone_number": "+49123123123",
- "birthday": "2019-08-24",
- "company_name": "ACME Inc."
}
}
Allows to update a visible user's profile by admin or org manager. Only applies to driver and customer users.
Partial updates (e.g. just first_name
) are not supported.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object or null (UserProfile) User's profile details.
|
{- "profile": {
- "first_name": "string",
- "last_name": "string",
- "phone_number": "+49123123123",
- "birthday": "2019-08-24",
- "company_name": "ACME Inc."
}
}
{- "profile": {
- "first_name": "string",
- "last_name": "string",
- "phone_number": "+49123123123",
- "birthday": "2019-08-24",
- "company_name": "ACME Inc."
}
}
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
Allows to retrieve opt-in configuration and status for the currently authenticated user account.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "opt_ins": [
- {
- "type": "marketing",
- "enabled": true,
- "required": true,
- "status": true
}
]
}
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.
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "opt_ins": {
- "marketing": true,
- "tracking": true
}
}
{- "opt_ins": [
- {
- "type": "marketing",
- "enabled": true,
- "required": true,
- "status": true
}
]
}
Show an invoice address for the current user.
Allowed when the feature is enabled for this user
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "address": {
- "first_name": "Han",
- "last_name": "Solo",
- "company_name": "Galactic Shipyard",
- "street": "Sunset Blvd.",
- "number": 42,
- "zip_code": 12345,
- "city": "string",
- "country_code": "DE",
- "additional_line": "House no. 3",
- "vat_number": "00/000/0000",
- "cif_number": "B12345678"
}
}
Set or update invoice address for the current user.
Partial updates for required fields is not allowed.
Allowed when the feature is enabled for this user
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
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. |
{- "address": {
- "first_name": "Han",
- "last_name": "Solo",
- "company_name": "Galactic Shipyard",
- "street": "Sunset Blvd.",
- "number": 42,
- "zip_code": 12345,
- "city": "string",
- "country_code": "DE",
- "additional_line": "House no. 3",
- "vat_number": "00/000/0000",
- "cif_number": "B12345678"
}
}
{- "address": {
- "first_name": "Han",
- "last_name": "Solo",
- "company_name": "Galactic Shipyard",
- "street": "Sunset Blvd.",
- "number": 42,
- "zip_code": 12345,
- "city": "string",
- "country_code": "DE",
- "additional_line": "House no. 3",
- "vat_number": "00/000/0000",
- "cif_number": "B12345678"
}
}
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.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
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. |
{- "address": {
- "first_name": "Han",
- "last_name": "Solo",
- "company_name": "Galactic Shipyard",
- "street": "Sunset Blvd.",
- "number": 42,
- "zip_code": 12345,
- "city": "string",
- "country_code": "DE",
- "additional_line": "House no. 3",
- "vat_number": "00/000/0000",
- "cif_number": "B12345678"
}
}
{- "address": {
- "first_name": "Han",
- "last_name": "Solo",
- "company_name": "Galactic Shipyard",
- "street": "Sunset Blvd.",
- "number": 42,
- "zip_code": 12345,
- "city": "string",
- "country_code": "DE",
- "additional_line": "House no. 3",
- "vat_number": "00/000/0000",
- "cif_number": "B12345678"
}
}
This endpoint returns the vouchers attached to the current user.
Current user must be a customer.
When Voucher feature is enabled, accessing this endpoint is permitted for customer's vouchers and any voucher for admins.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "results": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "added_at": "2019-08-24T14:15:22Z",
- "remaining_uses": 0,
- "voucher": {
- "code": "DISCOUNT10",
- "discount_percentage": 1
}
}
], - "meta": {
- "pagination": {
- "current_page": 1,
- "current_limit": 50,
- "max_limit": 500,
- "mode": "full",
- "total_pages": 42,
- "total_results": 2099
}
}
}
Attaches a voucher to the current user.
Current user must be a customer.
When Voucher feature is enabled, accessing this endpoint is permitted for customer's vouchers and any voucher for admins.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
code required | string (code) Code for the voucher that customers can use |
{- "code": "DISCOUNT10"
}
{- "customers_voucher": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "added_at": "2019-08-24T14:15:22Z",
- "remaining_uses": 0,
- "voucher": {
- "code": "DISCOUNT10",
- "discount_percentage": 1
}
}
}
Detaches a voucher to the current user.
Current user must be a customer.
When Voucher feature is enabled, accessing this endpoint is permitted for customer's vouchers and any voucher for admins.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "success": true
}
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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{
}
{- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
}
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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | Array of objects |
{- "invitations": [
- {
- "role": "admin",
- "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
- "auth_provider_key": "string",
- "external_id": "string"
}
]
}
{- "success": true,
- "invitations_count": 0
}
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.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "account_features": [
- {
- "completed": true,
- "skippable": true,
- "onboarding": true,
- "editable": true,
- "name": "profile_details",
- "attributes": [
- {
- "key": "first_name",
- "type": "string",
- "presence": "required"
}
]
}
]
}
List user accounts
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
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:
|
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 |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "results": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "role": "customer",
- "profile": {
- "first_name": "string",
- "last_name": "string",
- "phone_number": "+49123123123",
- "birthday": "2019-08-24",
- "company_name": "ACME Inc."
}, - "invoice_address": {
- "first_name": "Han",
- "last_name": "Solo",
- "company_name": "Galactic Shipyard",
- "street": "Sunset Blvd.",
- "number": 42,
- "zip_code": 12345,
- "city": "string",
- "country_code": "DE",
- "additional_line": "House no. 3",
- "vat_number": "00/000/0000",
- "cif_number": "B12345678"
}, - "status": "invited",
- "invited_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "email_verified_at": "2019-08-24T14:15:22Z",
- "capabilities": {
- "content_size": "large",
- "helper_count": "one"
}, - "organization": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "My Cool Organization"
}, - "managed_organizations": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "My Cool Organization"
}
], - "location": {
- "lat": 53.551085,
- "lng": 10.3824
}, - "service_area": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}, - "driver_requests_are_muted": true,
- "active_hailing_booking_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "can_change_organization": true,
- "anonymizable": true,
- "blockable": true,
- "unblockable": true,
- "blocked": true,
- "metadata": { },
- "external_identities": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "provider_key": "hello-world",
- "provider_name": "Hello world",
- "external_id": "string"
}
]
}
], - "meta": {
- "pagination": {
- "current_page": 1,
- "current_limit": 50,
- "max_limit": 500,
- "mode": "full",
- "total_pages": 42,
- "total_results": 2099
}
}
}
Fetches and displays the user with given ID
For drivers and customers only available on their own accounts
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "role": "customer",
- "profile": {
- "first_name": "string",
- "last_name": "string",
- "phone_number": "+49123123123",
- "birthday": "2019-08-24",
- "company_name": "ACME Inc."
}, - "invoice_address": {
- "first_name": "Han",
- "last_name": "Solo",
- "company_name": "Galactic Shipyard",
- "street": "Sunset Blvd.",
- "number": 42,
- "zip_code": 12345,
- "city": "string",
- "country_code": "DE",
- "additional_line": "House no. 3",
- "vat_number": "00/000/0000",
- "cif_number": "B12345678"
}, - "status": "invited",
- "invited_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "email_verified_at": "2019-08-24T14:15:22Z",
- "capabilities": {
- "content_size": "large",
- "helper_count": "one"
}, - "organization": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "My Cool Organization"
}, - "managed_organizations": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "My Cool Organization"
}
], - "location": {
- "lat": 53.551085,
- "lng": 10.3824
}, - "service_area": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}, - "driver_requests_are_muted": true,
- "active_hailing_booking_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "can_change_organization": true,
- "anonymizable": true,
- "blockable": true,
- "unblockable": true,
- "blocked": true,
- "metadata": { },
- "external_identities": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "provider_key": "hello-world",
- "provider_name": "Hello world",
- "external_id": "string"
}
]
}
}
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.
Permitted unless this is an internal system user like the dispatch customer
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "success": true
}
Update the given user's metadata, replacing any existing metadata on the user.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object (Metadata) |
{- "user": {
- "metadata": { }
}
}
{- "success": true
}
Update the given user's metadata for the given keys, preserving any metadata keys that were not sent.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object (Metadata) |
{- "user": {
- "metadata": { }
}
}
{- "success": true
}
Fetch the PDF documents for the user.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
user_id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "documents": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "representations": {
- "small_square": {
- "url": "string"
}, - "display": {
- "url": "string"
}
}, - "filename": "Project Plan (final).pdf"
}
]
}
Update the user's PDF documents.
This endpoint works in a way that you should always provide the IDs of the documents that you want the user to have. So in case that there are existing documents and you want to upload a new one, you should send both the existing IDs and the new IDs. Similarly, in the case where you want to remove some documents, you should provide the list of IDs without the IDs of those documents.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
user_id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | documents_request (string) or (Array of documents_request (strings or null)) (documents_request) List of UUIDs of Uploads that should be used for attaching as documents. The UUIDs passed here are returned from the generic file uploads endpoint
on successful upload and must be of type |
{- "documents": "117f7992-66ce-4ba8-bec7-dc516f479ad2"
}
{- "documents": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "representations": {
- "small_square": {
- "url": "string"
}, - "display": {
- "url": "string"
}
}, - "filename": "Project Plan (final).pdf"
}
]
}
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.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "success": true
}
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.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "success": true
}
Allows re-delivery of the welcome e-mail to the given customer.
Permitted only on customer accounts which don't have their e-mail verified and when the welcome e-mail is actually enabled.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
user_id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "success": true
}
Export user data in CSV format.
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
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 |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
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,,"",
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.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "opt_ins": [
- {
- "type": "marketing",
- "enabled": true,
- "required": true,
- "status": true
}
]
}
These endpoints are used for handling payment methods available to a user.
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.
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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "enabled_payment_methods": [
- "cash",
- "credit_card"
], - "manually_activated_payment_methods": [
- "credit_card"
], - "currently_activated_payment_methods": [
- "credit_card"
]
}
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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
required | object |
{- "user": {
- "activated_payment_methods": [
- "invoice"
]
}
}
{- "enabled_payment_methods": [
- "cash",
- "credit_card"
], - "manually_activated_payment_methods": [
- "credit_card"
], - "currently_activated_payment_methods": [
- "credit_card"
]
}
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 for a given driver ID.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "user": {
- "driver_requests_are_muted": true
}
}
Unmute driver requests for a given driver ID.
id required | string <uuid> (uuid) UUID identifier of the resource |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "user": {
- "driver_requests_are_muted": true
}
}
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 to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "defaults": { },
- "configuration": {
- "assign_service_area": {
- "enabled": true
}
}
}
Returns a list of organizations visible to current user
Permissions to access this endpoint.
admin | customer | driver | org_manager |
---|---|---|---|
β | β | β | β |
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:
|
Accept | string Example: application/json The requested response body content type. At this time we only support
|
Accept-Language | string Example: en Locale code of the preferred language of the client. See Localization for further details. |
Content-Type | string Example: application/json Indicates the content type of the request body, if applicable. We support
|
X-Client-Version | string Example: ACME Inc. iOS Customer/1.3.0 Indicates the client that is making the request. See Client Identification |
{- "results": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "My Cool Organization",
- "legal_entity_type": "individual",
- "business_tax_id": "string",
- "metadata": { },
- "address": {
- "first_name": "John",
- "last_name": "Cena",
- "location_name": "WWE Arena",
- "street": "WarnholtzstraΓe",
- "number": 42,
- "additional_line": "House